原理与源码导览(含决策迁移)
本阶段串联起交互界面、HTTP 回环服务、CAS 并发控制与双源持久化,并直接复用仓库 repo-docs/ 的真实走读与代码位置索引,同时记录已确认的协议与数据迁移决策。
系统分层与存储拓扑
- 交互层(
web/):dashboard.html+app.js构成双栏主从工作台、三段式详情驾驶舱与专注批阅流;markdown.js禁用原生 HTML 并校验链接协议,diagrams.js离线封装web/vendor/mermaid-12.1.0.min.js(strict 模式、5 万字符与 500 边上限),agent-question.js仅解析最新一轮有效单选围栏。 - 回环接入与锁边界(
core/server.py、core/locking.py):基于 Python 标准库ThreadingHTTPServer,按请求校验证书/Origin/Sec-Fetch-Site/回环来源;业务写入通过基于规范化database_path的进程内可重入锁串行协调。 - 业务编排与权威文件(
core/decision_service.py、core/markdown_parser.py):写操作在覆写decisions/<id>.md前必须通过_validate_document往返解析检验并执行原子替换;Markdown 承载每个议题的当前全部正文与讨论轮次。 - 快照历史、一致性与可选提交(
core/db.py、core/recovery.py、core/git_engine.py):SQLitedecisions.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:
{
"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 表:
- 若
request_id存在且参数指纹一致,已完成的请求直接返回带is_replay: true的原响应;若处于applied或git_status == "pending"的中间态,则执行_resume_pending_phases续做摘要导出与可选 Git 提交,而不会再次追加讨论轮次。 - 若同一
request_id携带了不同expected_version或不同载荷,服务抛出IdempotencyConflictError,HTTP 层返回409。 - 校验
expected_version与当前库内版本及topic_version_seq单调序号一致(防止 ABA 错位);构造新内容后先调用_validate_document对 Markdown 文本做解析/反序列化往返校验,防止未闭合围栏或协议标题污染正文,再原子替换写入decisions/<id>.md。 - 随后更新 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 再次提交,否则会制造重复讨论轮次。
收到响应并落盘本地回执后,调用方应运行只读写入后钩子核对一致性:
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)。在仓库根目录使用临时隔离目录运行的完整回归命令为:
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.py | SQLite 建表与迁移、ABA 单调序列、幂等键、修订快照与在线热备 | DatabaseManager.upsert_topic, check_idempotency, commit_revision, backup_database |
core/markdown_parser.py | schema_version: "2.0" Frontmatter 与围栏感知讨论解析/拼装 | TopicMarkdownParser.parse_markdown_text, amend_round, serialize_markdown |
core/recovery.py | 摘要摘要比对、从权威 Markdown 重筑 topics 与导出 metadata.json | RecoveryManager.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 | 回环只读任务前后钩子与一致性预检 CLI | AgentHooks.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。
关键边界与决策迁移
以下演进均已落地当前代码,升级旧台账目录或迁移旧脚本时请重点核对:
- 三轴正交状态与旧
decision_outcome别名迁移:- 旧格式允许在
decision_outcome中填写"deferred"或"superseded";当前版本通过LEGACY_PROGRESS_OUTCOMES在读取时将其映射为workflow_state并把decision_outcome置空(不自动改写磁盘旧文件)。 - 仅当对该议题执行正常保存或恢复时,才会升级写回
schema_version: "2.0"的独立workflow_state+decision_outcome+implementation_state三轴字段。
- 旧格式允许在
- 安全归档删除替代直接删档(
delete_topic):- 删除议题不再直接抹除
.md文件,而是移入decisions/.archived_rollback/<id>_<随机后缀>.md并写入带prior_rev_id的TOPIC_REMOVE快照;调用POST /api/topic/<id>/restore或全局回滚即可按需撤销。
- 删除议题不再直接抹除
- 视图范围收敛(
topic_scope.active_topic_ids):- 当老项目积累大量历史议题时,无需从磁盘删除旧
.md或改历史库:只需在dashboard.config.json配置topic_scope.active_topic_ids数组,工作台列表与GET /api/agent/context会自动收敛为活跃议题视图,同时保留/api/topic/<id>直接查阅历史议题的能力。
- 当老项目积累大量历史议题时,无需从磁盘删除旧
doc_data_json_path配置键定位调整:DEFAULT_CONFIG仍保留doc_data_json_path键名以兼容既有配置,但当前版本不再将该文件作为权威导入或重建来源,摘要统一导出至metadata_json_path,权威数据始终以decisions_dir/*.md与database_path为准。
源码证据与验证边界
提交任何影响业务或前端交互的修改后,请在独立测试目录下运行完整验证(切勿直接对日常运行中的用户 decisions.db 执行重建或测试):
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文档构建与结构检查(面向仓库维护者):
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。