API与可观察数据

所有路径相对http://localhost:8000。设置API_KEY后，每个/api/请求必须携带X-API-Key；工作台支持输入此值，网页不会持久化密钥。/health与静态工作台不要求密钥。本系统是本地单用户学习服务，没有生产多租户身份系统。

方法与路径	输入	输出/用途
POST /api/jobs	Request主题、等级、语言、地区、book_id、修订上限、场景	job，后台开始执行
GET /api/jobs	无	最近100个任务
GET /api/jobs/	job id	job、versions、reviews、tasks、最近300个events
GET /api/jobs/{id}/diff	before、after版本参数	按稳定block ID比较内容
POST /api/jobs/{id}/decision	action、expected_version、note、edits、override	人工通过/退回/终止入队
POST /api/jobs/{id}/edit	expected_version、edits、note	新教材版本、新epoch、审核失效
POST /api/jobs/{id}/recover	无	失败恢复原线程；终止恢复新epoch
GET /api/jobs/{id}/delivery	无	最新批准且资源完整的ZIP
POST /api/documents	name/text/level/language/region/source_url/facts	资料版本、chunk数量、namespace
GET /api/documents	无	全部资料版本与active标记
GET /api/search	query、level、language、region、strategy	片段、文档/版本、offset、score
GET/POST /api/rules	Rules结构	读取或保存更高版本地区规则
POST /api/tasks/{id}/resolve	reconcile或retry；重复风险确认	回执核对或明确重试
GET /api/tasks/{id}/asset	task id	已成功任务对应资源

完整字段约束从运行中的/docs、/openapi.json与python -m app.cli schemas获取，避免手写文档与Schema漂移。

人工通过示例

先查询任务，替换JOB_ID和expected_version，不要把示例数字当成永远正确：

bash

curl -X POST http://localhost:8000/api/jobs/JOB_ID/decision \
  -H 'Content-Type: application/json' \
  -d '{"action":"approve","expected_version":2,"note":"已核对教材与来源"}'

旧版本返回409；仍有error/critical问题返回400。必须人工明确给出override=true和理由才能覆盖问题，覆盖不会伪装成评审通过。

局部修订示例

json

{
  "expected_version": 2,
  "edits": [{
    "block_id": "c1-practice",
    "text": "请计算：2 + 2 = ?",
    "translation": "Calculate: 2 + 2 = ?",
    "answer": "4"
  }],
  "note": "修正参考答案"
}

人工编辑允许修改现有块，不提供章节增删或任意JSON Patch。编辑不默默复用旧批准；新版本必须重新评审。结构性修改目前应建立新任务，这是已知范围，不是假装有完整富文本编辑器。

事件读法

从retrieved看到资料范围与冲突；从model_call看到role、上下文hash、Token和耗时；从tool_denied识别越权；从version_saved/reviewed定位教材变化；从task_finished/lease_recovered看失败恢复；从asset_reused理解内容寻址；delivery_ready才代表当前版本可交付。

事件不是完整审计系统：默认最多返回300条，没有分页导出与保留周期策略。没有记录模型隐藏思维链；可追踪的是必要输入快照、结构化结果与执行事件。

API与可观察数据 ​

人工通过示例 ​

局部修订示例 ​

事件读法 ​

API与可观察数据

人工通过示例

局部修订示例

事件读法