# AI 法律咨询智能助手

这是一个已接入 Codex Skill/MCP 的证据型法律咨询项目。它复刻了原文心工作流的两层路由：先优化问题并识别劳动法意图，再进入劳动法知识库或公网检索分支；所有回答都保留引用、降级原因和调用追踪信息。网页入口为「法律法规智能查询」，核心工作流可在 Codex / MCP / 脚本中复用。

## 已复刻的工作流

| 原工作流节点 | 本项目实现 |
| --- | --- |
| 查询优化 | DeepSeek V4 Flash；失败时使用规范化原问题 |
| 意图识别 | 模型仅输出劳动法“是/否”；失败时使用显式关键词规则并标记降级 |
| 嵌套工作流 | 二次优化知识库查询，检索《劳动法》《劳动合同法》，基于证据回答 |
| 公网搜索 | 调用可配置的 HTTP 搜索接口，基于搜索证据与链接回答 |
| 选择器 | 劳动法进入知识库，其他问题进入公网；知识库异常可配置转公网 |
| 输出 | `answer`、`citations`、`warnings`、`fallback_reasons`、`trace_id`，兼容 `output1/output2` |

完整节点与异常语义见 [docs/workflow-spec.md](docs/workflow-spec.md)。产品需求见 [docs/PRD.md](docs/PRD.md)，接口契约见 [.agents/skills/consult-chinese-labor-law/references/workflow-contract.md](.agents/skills/consult-chinese-labor-law/references/workflow-contract.md)。

## 启动网站

1. 将 `.env.example` 复制为 `.env.local`。
2. 填写 `DEEPSEEK_API_KEY`。处理非劳动法问题时，还需填写百度 AI 搜索的 `PUBLIC_SEARCH_API_KEY`。
3. 安装依赖并启动：

```powershell
npm install
npm --prefix plugins/ai-legal-consultant/server/node install
npm run dev
```

打开 `http://localhost:3001`。

`LEGAL_WORKFLOW_MODE` 支持三种模式：

- `custom`：强制使用本项目复刻的 DeepSeek/知识库/公网工作流。
- `wenxin`：保留并强制使用原文心 Conversation API。
- `auto`：有 DeepSeek Key 时使用新工作流；否则在文心凭据存在时继续使用原接口。

未配置远程知识库时，劳动法分支自动使用项目内两部法律的本地快照。百度搜索 Key 未配置时，非劳动法分支会明确报告配置缺失，不会让模型凭记忆猜测。

## 在 Codex 中调用

项目级 Skill 位于 `.agents/skills/consult-chinese-labor-law`。重新打开本项目或开始一个新任务后，可直接说：

```text
$consult-chinese-labor-law 公司拖欠三个月工资，我应该如何维权？
```

Skill 优先调用 MCP 工具 `consult_legal_question`；MCP 不可用时，会退回项目内 Node.js 脚本。可分发插件位于 `plugins/ai-legal-consultant`，本地插件市场清单位于 `.agents/plugins/marketplace.json`。

## 直接调用函数

Node.js：

```js
import { createWorkflowFromEnv } from "./plugins/ai-legal-consultant/server/node/index.mjs";

const result = await createWorkflowFromEnv().consult("公司拖欠工资怎么办？");
console.log(result.answer, result.citations);
```

Python：

```powershell
cd plugins/ai-legal-consultant/server/python
python -m pip install -e .
```

```python
from legal_workflow import create_workflow_from_env

result = create_workflow_from_env().consult("公司拖欠工资怎么办？")
print(result.answer, result.citations)
```

## 配置接口

- `DEEPSEEK_API_KEY`：DeepSeek API Key。
- `DEEPSEEK_MODEL`：默认 `deepseek-v4-flash`。
- `LEGAL_KB_URL` / `LEGAL_KB_API_KEY`：可选远程知识库 HTTP 适配器。
- `PUBLIC_SEARCH_PROVIDER`：本项目固定为 `baidu`。
- `PUBLIC_SEARCH_URL`：百度官方接口 `https://qianfan.baidubce.com/v2/ai_search/web_summary`；不要填写百度网页首页。
- `PUBLIC_SEARCH_API_KEY`：百度千帆 AI 搜索 API Key，与 DeepSeek Key 分开。
- `LEGAL_ALLOW_WEB_FALLBACK_ON_KB_ERROR`：知识库发生异常时是否转公网；知识库正常但无结果时不会静默改道。

接口契约和请求/响应 JSON 见 [工作流契约](.agents/skills/consult-chinese-labor-law/references/workflow-contract.md)。不要提交 `.env.local` 或任何真实密钥。

## 验证

```powershell
npm test
npm run lint
cd plugins/ai-legal-consultant/server/python
$env:PYTHONPATH="src"
python -m unittest discover -s tests -v
```

Node 测试同时覆盖 MCP 真实进程握手和工具调用。回答仅供法律信息参考，不构成正式法律意见。