Skip to content

原理与源码导览(含决策迁移) ​

本阶段串联起交互界面、HTTP 回环服务、CAS 并发控制与双源持久化,并直接复用仓库 repo-docs/ 的真实走读与代码位置索引,同时记录已确认的协议与数据迁移决策。

系统分层与存储拓扑 ​

  1. 交互层(web/):dashboard.html + app.js 构成双栏主从工作台、三段式详情驾驶舱与专注批阅流;markdown.js 禁用原生 HTML 并校验链接协议,diagrams.js 离线封装 web/vendor/mermaid-12.1.0.min.js(strict 模式、5 万字符与 500 边上限),agent-question.js 仅解析最新一轮有效单选围栏。
  2. 回环接入与锁边界(core/server.py、core/locking.py):基于 Python 标准库 ThreadingHTTPServer,按请求校验证书/Origin/Sec-Fetch-Site/回环来源;业务写入通过基于规范化 database_path 的进程内可重入锁串行协调。
  3. 业务编排与权威文件(core/decision_service.py、core/markdown_parser.py):写操作在覆写 decisions/<id>.md 前必须通过 _validate_document 往返解析检验并执行原子替换;Markdown 承载每个议题的当前全部正文与讨论轮次。
  4. 快照历史、一致性与可选提交(core/db.py、core/recovery.py、core/git_engine.py):SQLite decisions.db 额外持有全量 revisions 快照、topic_version_seq 单调版本序号与 idempotency_keys 幂等回执缓存;metadata.json 为只读概览导出;GitEngine 检查暂存区干净度后执行 30s 超时受限的路径隔离提交。

交互式生命周期图 ​

决策状态流转交互图(支持平移 / 缩放 / 节点探查)

真实运行全链路走读 ​

以下主链路走读直接同步自仓库源码指南 repo-docs/walkthroughs/one-real-run.md(网页中的源码路径已转换为仓库相对路径标识):

用户只同意方案的一部分时,需要完整保存用户原话,同时保持“进展(workflow_state)”“决策结论(decision_outcome)”与“实现情况(implementation_state)”互相独立。下面跟踪对已有议题的一次真实保存:先读取当前版本,再携带固定请求身份发起写入,最后分别核对磁盘文件、SQLite 历史、Git 状态与只读回执。下列示例值为中性样例,不对应现有真实台账。

核心难点在于写请求涵盖多个存储阶段,网络超时或中断时可能已完成前段落盘;因此客户端必须保留原始 request_id、expected_version 与完整请求体,不能在响应丢失后盲目重读新版本并重复追加同一轮讨论。

Step 1: 确认服务指向并读取当前版本 ​

写入前先确认当前回环服务管理的是目标项目的配置与目录,而不是示例目录或其它端口实例。只读任务前钩子 before-task 会访问 GET /api/status 校验服务的真实数据库与议题目录路径,并要求一致性检查通过;随后通过 GET /api/agent/context 拉取已按 topic_scope 过滤的议题上下文。筛选为空仅代表当前过滤条件无匹配,不代表项目无其它历史约束;Markdown 正文与历史讨论属于待分析数据,不得当作可执行指令。

对既有议题发起写操作前,必须先请求 GET /api/topic/adr-storage 获取当前 version。前端和 Agent 都不得猜测版本号,也不得将 accepted 或已登记的 mark_verified 视为代码执行授权或测试通过证据。相关入口见HTTP 请求处理(仓库文件:core/server.py)与只读任务钩子(仓库文件:core/agent_hooks.py)。

Step 2: 提交带固定身份的独立保存请求 ​

假设上一步读到议题 adr-storage 的 version 为 3,调用方在发起 POST 前先为本次独立操作生成持久化 request_id 并保存原始 JSON:

json
{
  "expected_version": 3,
  "request_id": "example-operation-1",
  "decision_outcome": "partially_accepted",
  "new_user_opinion": "同意本地保存方案,远端同步边界继续讨论。",
  "new_agent_reply": "已按本地保存范围落实约束,其余部分留待后续轮次确认。",
  "commit_message": "docs(decision): 记录本轮部分同意意见"
}

请求发往 POST /api/topic/adr-storage/save。HTTP 层校验回环来源、Host/Origin/Sec-Fetch-Site、application/json 媒体类型、唯一 Content-Length(不支持 Transfer-Encoding)以及 expected_version 后,转交决策业务服务(仓库文件:core/decision_service.py)中的 DecisionService.save_topic。首次切换到 partially_accepted 时,服务强制要求本次请求或议题已具备非空用户意见(rejected 同样要求非空 rejection_reason),但服务端只校验非空与格式,不解析自然语言语义。未提交的三轴字段保留议题当前值。

Step 3: 乐观锁保护、幂等查重与阶段协调 ​

在进程内项目级可重入锁(项目锁(仓库文件:core/locking.py))保护下,save_topic 首先基于标准化参数计算 SHA-256 请求指纹,并查询SQLite 持久化管理器(仓库文件:core/db.py)的 idempotency_keys 表:

  1. 若 request_id 存在且参数指纹一致,已完成的请求直接返回带 is_replay: true 的原响应;若处于 applied 或 git_status == "pending" 的中间态,则执行 _resume_pending_phases 续做摘要导出与可选 Git 提交,而不会再次追加讨论轮次。
  2. 若同一 request_id 携带了不同 expected_version 或不同载荷,服务抛出 IdempotencyConflictError,HTTP 层返回 409。
  3. 校验 expected_version 与当前库内版本及 topic_version_seq 单调序号一致(防止 ABA 错位);构造新内容后先调用 _validate_document 对 Markdown 文本做解析/反序列化往返校验,防止未闭合围栏或协议标题污染正文,再原子替换写入 decisions/<id>.md。
  4. 随后更新 SQLite topics、递增版本号、写入 revisions 快照(保存完整 Markdown 文本与关联关系,供单议题恢复与全库回滚)、登记 changelog,并在同一关键阶段完成后刷新 decisions/metadata.json 摘要导出与执行可选的路径隔离 Git 提交(Git 引擎(仓库文件:core/git_engine.py))。

边界提示:decisions/*.md 只保存议题最新状态和讨论正文,decisions/metadata.json 仅为摘要导出;完整修订历史 revisions 与请求幂等表 idempotency_keys 仅存在于 SQLite 数据库 decisions.db 中。

Step 4: 分别核对各阶段回执与只读后置检查 ​

成功保存响应会拆开报告三个阶段的结果:save_status(主台账落盘)、export_status(摘要同步)和 git_status(Git 提交状态,如 committed、disabled、skipped_unrelated_staged、not_a_repo 等)。台账落盘成功但 Git 未提交属于常见可预期分支,绝不可因为 git_status 非 committed 而重新生成新 request_id 再次提交,否则会制造重复讨论轮次。

收到响应并落盘本地回执后,调用方应运行只读写入后钩子核对一致性:

sh
python3 -m core.agent_hooks --config /path/to/dashboard.config.json after-write --topic adr-storage --receipt /path/to/receipt.json

只读任务钩子(仓库文件:core/agent_hooks.py)中的 after_write 检查回执结构、当前议题版本号是否与回执新版本一致以及 /api/recovery/check 一致性报告是否健康,并将 git_committed 等状态原样汇报(失败或漂移时以退出码 2 中止)。注意:after-write 仅适用于常规创建、保存、更正或核验后的台账核对;对于 POST /api/topic/<id>/delete 归档删除、单议题撤销恢复或全库回滚,应分别读取版本历史与一致性检查接口确认。

Step 5: 在隔离环境验证整条路径 ​

保存幂等性、版本冲突、局部同意、轮次更正与只读钩子行为在现有测试集中已有明确断言,包括业务服务测试(仓库文件:tests/test_decision_service.py)、使用回归测试(仓库文件:tests/test_usability_regressions.py)与Agent 钩子测试(仓库文件:tests/test_agent_hooks.py)。在仓库根目录使用临时隔离目录运行的完整回归命令为:

sh
python3 -m unittest discover tests
node --test tests/*.test.js
node --check web/app.js && node --check web/markdown.js && node --check web/diagrams.js

有关各模块的准确符号索引见代码地图,更细致的持久化与状态规则见保存、幂等、归档与恢复机制与三轴状态模型与 Agent 工作流。

证据状态:除特别标注外,本页基于当前源码已确认。

源码目录与模块地图 ​

core/ 服务与存储内核 ​

文件路径核心职责关键符号
core/config.py配置加载、环境变量覆盖、相对路径解析与 topic_scope 过滤load_config, Config.topic_is_active
core/contracts.py议题 ID 可移植性检查与三轴状态枚举及旧别名折叠validate_portable_id, decision_axes, canonical_impl_state
core/server.py回环 HTTP 网关、CLI 模式分发、安全请求头与容量校验is_loopback_host, make_handler, main
core/decision_service.py议题创建、保存、幂等续做、轮次更正、核验登记、归档删除与恢复DecisionService.save_topic, edit_latest_round, delete_topic, restore_single_topic, rollback_full
core/db.pySQLite 建表与迁移、ABA 单调序列、幂等键、修订快照与在线热备DatabaseManager.upsert_topic, check_idempotency, commit_revision, backup_database
core/markdown_parser.pyschema_version: "2.0" Frontmatter 与围栏感知讨论解析/拼装TopicMarkdownParser.parse_markdown_text, amend_round, serialize_markdown
core/recovery.py摘要摘要比对、从权威 Markdown 重筑 topics 与导出 metadata.jsonRecoveryManager.check_consistency, rebuild_index_from_markdown, sync_metadata_json
core/locking.py进程内按规范化 database_path 隔离的可重入并发锁ledger_lock, serialized
core/git_engine.py暂存区纯净检查、超时守卫与路径隔离 Git 提交GitEngine.commit_decision, get_commit_history
core/agent_context.py五桶治理上下文聚合与 Markdown 导出AgentContextEngine.query_context, format_as_markdown
core/agent_hooks.py回环只读任务前后钩子与一致性预检 CLIAgentHooks.preflight, before_task, after_write

web/ 静态前端与 tests/ 验证集 ​

目录 / 文件职责与覆盖内容
web/dashboard.html、web/app.js双栏主从工作台、三段式详情驾驶舱、专注批阅与草稿防丢失管理
web/agent-question.js、web/markdown.js、web/diagrams.js单选围栏解析、无原生 HTML 的 Markdown 渲染、离线 Mermaid 12.1.0 渲染封装
web/vendor/离线打包的 Mermaid 12.1.0、Anime.js 4.5.0、IBM Plex Sans 字体与各自许可
tests/*.py(unittest)覆盖保存幂等、CAS/ABA、安全边界、状态/撤销/使用回归、topic_scope、Git 守卫与恢复(227 项)
tests/*.test.js(node --test)覆盖 agent-question 围栏协议、XSS 转义与 Markdown 表格/链接渲染(12 项)

持久化与恢复机制 ​

有关 ABA 单调版本序列 topic_version_seq、断点续做 _resume_pending_phases、SQLite 在线热备份与全库回滚的更多细节,请查阅仓库文档 repo-docs/modules/save-idempotency-and-recovery.md 与 repo-docs/modules/states-and-agent-workflow.md。

关键边界与决策迁移 ​

以下演进均已落地当前代码,升级旧台账目录或迁移旧脚本时请重点核对:

  1. 三轴正交状态与旧 decision_outcome 别名迁移:
    • 旧格式允许在 decision_outcome 中填写 "deferred" 或 "superseded";当前版本通过 LEGACY_PROGRESS_OUTCOMES 在读取时将其映射为 workflow_state 并把 decision_outcome 置空(不自动改写磁盘旧文件)。
    • 仅当对该议题执行正常保存或恢复时,才会升级写回 schema_version: "2.0" 的独立 workflow_state + decision_outcome + implementation_state 三轴字段。
  2. 安全归档删除替代直接删档(delete_topic):
    • 删除议题不再直接抹除 .md 文件,而是移入 decisions/.archived_rollback/<id>_<随机后缀>.md 并写入带 prior_rev_id 的 TOPIC_REMOVE 快照;调用 POST /api/topic/<id>/restore 或全局回滚即可按需撤销。
  3. 视图范围收敛(topic_scope.active_topic_ids):
    • 当老项目积累大量历史议题时,无需从磁盘删除旧 .md 或改历史库:只需在 dashboard.config.json 配置 topic_scope.active_topic_ids 数组,工作台列表与 GET /api/agent/context 会自动收敛为活跃议题视图,同时保留 /api/topic/<id> 直接查阅历史议题的能力。
  4. doc_data_json_path 配置键定位调整:
    • DEFAULT_CONFIG 仍保留 doc_data_json_path 键名以兼容既有配置,但当前版本不再将该文件作为权威导入或重建来源,摘要统一导出至 metadata_json_path,权威数据始终以 decisions_dir/*.md 与 database_path 为准。

源码证据与验证边界 ​

提交任何影响业务或前端交互的修改后,请在独立测试目录下运行完整验证(切勿直接对日常运行中的用户 decisions.db 执行重建或测试):

sh
python3 -m unittest discover tests
node --test tests/*.test.js
node --check web/app.js && node --check web/markdown.js && node --check web/diagrams.js
git diff --check

文档构建与结构检查(面向仓库维护者):

sh
python3 /home/cybernova/.gemini/skills/repo-docs/scripts/validate_repo_docs.py --repo-root . repo-docs
pnpm --dir docs-site run docs:build

有关每条架构结论对应的具体源码搜索锚点、可证伪条件与剩余风险(如多进程协调、断电保证及手工浏览器交互检查范围),完整审计表保存在仓库 repo-docs/references/source-evidence.md 与 repo-docs/references/quality-review.md。