从对话到可信交付：AI 任务账本方法论、实施与商业落地白皮书

• 版本：v2.0
• 基准日期：2026-08-28
• 产品形态：本地优先的跨 Agent 任务审计、实施与交付方案
• 事实口径：已实现、当前机已验证、历史已验证、待客户机验证、规划中

1. 为什么聊天记录不能代替任务系统

AI 工作从对话开始，但交付通常落在代码、文档、图片、网页、命令和外部系统。聊天记录能解释上下文，却很难稳定回答：今天正式承诺了哪些工作；哪项只是讨论；同一个需求是否被重复建卡；实现、测试和用户验收分别到了哪一步；换电脑或换 Agent 后从哪里继续。

传统待办工具也存在空白。它往往只保存标题和截止时间，无法自动保留客户端来源、设备、会话、项目、工具调用、完成证据和跨设备轨迹。把每句话都变成待办又会制造大量噪声。

AI 任务账本在对话和交付之间增加一层可审计协议：先保留候选入口，再识别正式任务；用不可变事件记录变化；由可重建视图服务人类阅读；用证据而不是模型语气决定完成度。

2. 核心价值

2.1 不漏

客户端 Hook 捕获用户提交、第一次工具调用和回合结束。即使 Agent 忘记手工写卡，也有候选和轻量自动登记入口。

2.2 不重复

同会话的同义改述、修正、追问或补充复用原任务；新增要求追加到原目标，不另建近义卡。

2.3 不假完成

“代码写完”“测试通过”“客户确认”和“另一台电脑已同步”是不同证据层。任务状态只使用待开始、进行中、待验证、已完成、阻塞。

2.4 可跨端、跨设备继续

任务记录创建来源、参与来源、创建设备、参与设备。来源表示客户端，不表示触发角色；Codex 自动化仍是 codex，Claude App 中的用户消息仍是 claude。

2.5 可恢复

正式任务权威事件按文件分片进入 Git。本机 SQLite、日报和 STATUS 生成页损坏时，可从分片重新构建。

3. 典型客户

• 同时使用 Codex、Claude App 和 Hermes 的个人开发者或内容团队；
• 在台式机和笔记本之间切换的多设备用户；
• 需要用任务卡、测试和提交证据向客户交付的工作室；
• 希望保留本地隐私，不把完整聊天上传到额外 SaaS 的团队；
• 已有项目任务规范，希望增加跨项目总账而非替换项目管理的组织。

不建议直接用于强监管审计、多人高并发工单、细粒度企业权限或需要中心化 SLA 的场景。此类客户应在本地方案上增加服务端数据库、身份、权限和审计保留策略。

4. 产品边界

5. 设计原则

1. 采集、判断、存储、展示分层；
2. 同一实质任务只有一个主任务编号；
3. 状态结论必须能回到证据；
4. 不可变事件优于共享大文件；
5. 客户端来源和物理设备是两个独立维度；
6. 用户级 Hook 不随仓库假装同步；
7. 不确定时保守，不错误合并、不虚构完成；
8. 本地提交、远端同步、目标机验收分别陈述。

6. 商业表达建议

对外可以描述为“本地优先的跨 Agent 任务审计与交付系统”，而不是“完全自动的 AI 项目经理”。前者与当前实现一致：它能捕获、登记、续办、流转、重建和验证；后者会暗示尚未具备的资源调度、权限中心、自动排期和多人实时协同。

7. 功能需求总表

8. 系统架构

flowchart TB
    A[Codex] --> H[用户级 Hook]
    B[Claude App / Claude Code] --> H
    C[Hermes Agent] --> H
    H --> D[三端适配器]
    D --> E[候选审计 本机 SQLite]
    D --> F[任务记录器 CLI]
    F --> G[主任务不可变事件]
    F --> L[双链不可变事件]
    F --> R[注册表不可变事件]
    G --> V[任务卡/日报/STATUS 生成视图]
    L --> V
    R --> V
    G --> Git[受控 Git 仓库]
    L --> Git
    R --> Git

Hook 做快速、确定、失败开放的工作；适配器把不同客户端负载转换为统一字段；记录器负责幂等、状态、事件写入和视图重建；当前 Agent 负责完整语义拆分、纠偏和证据判断。

9. 数据分层

每个 v2 事件以 sha256(event_id) 命名。相同 ID、相同内容重放保持幂等；相同 ID、不同内容快速失败。禁止直接改写或删除既有分片，纠错通过新事件表达。

10. 状态与同会话规则

stateDiagram-v2
    [*] --> 待开始: 实质请求
    待开始 --> 进行中: 第一次工具调用
    进行中 --> 待验证: 形成交付和证据
    进行中 --> 阻塞: 缺授权/输入/外部条件
    待验证 --> 已完成: 同会话明确验收
    进行中 --> 已完成: 确认开启独立新任务且前项已有证据
    待验证 --> 已完成: 确认开启独立新任务

在同一会话收到后续消息时，先分类：

• 同一任务：同义改述、修正、追问或补充，调用 continue --supplement；
• 独立新任务：创建新任务，并完成最近的待验证/进行中前项；
• 不确定：不新建、不完成，交由 Agent 结合完整对话判断；
• 阻塞或跨会话旧任务：不自动完成。

Agent 结束不直接等于完成。Stop/PostLlmCall 只收口到待验证或阻塞。Claude App 可能在设计流程切到项目子目录；收口允许祖先项目匹配，但仍要求结构化任务 ID、会话和项目关系一致。

11. 来源、用户和设备

origin 表示写入任务的客户端或明确的人工入口：

• codex：Codex Desktop、CLI、自动化及其后续对话；
• claude：Claude App 内置 Claude Code、Claude Code CLI/IDE；
• hermes：Hermes CLI/Gateway；
• webui：任务看板应用发起的写入；
• user：用户通过明确人工/管理命令直接写入。

webui 不是 user 的别名。前者说明写入经过哪个应用，后者说明人工直接入口；两者需要独立统计和权限治理。触发消息的角色仍可在候选或业务字段表达，但不应污染来源 ID。

设备通过规范 ID、显示名、类型、别名和状态管理。选择顺序是显式 --device-id、TASK_LEDGER_DEVICE、macOS ComputerName、hostname、unknown。GUI 应用未必继承 shell 环境，因此客户交付必须检查真实事件中的设备值。

12. 多设备与双链

不同设备新增不同事件文件，降低共享大 JSON 的 Git 冲突。开始工作仍需人工 git pull --ff-only；失败时停止，不能自动 stash、reset 或强行合并。绑定到项目任务卡后，只有活动设备可写，并可使用交接请求和接受事件转移控制权。

这种架构适合个人和小团队串行协作。多人同时编辑同一业务任务时，Git 可以保存事件，不能替人解决语义冲突；需要高并发时应升级为带身份和事务的服务端。

13. 安装前清单

客户需要准备：受支持的 macOS、Python 3、Git 仓库权限、目标客户端、可修改用户级配置的本机账号，以及每台设备的规范 ID。记录真实值：

whoami
scutil --get ComputerName
python3 --version
git --version

设定占位符：

<AI_OS_ROOT> = /Users/<USER>/AI_OS
<DEVICE_ID>  = 客户批准的稳定设备 ID

不要把真实 API Key、OAuth token、Cookie 或客户敏感任务写入安装文档。

14. 获取和校验仓库

git clone <REPO_URL> <AI_OS_ROOT>
cd <AI_OS_ROOT>
git switch main
git pull --ff-only
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> sync
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> validate

已有仓库先执行 git status --short --branch。pull --ff-only 失败时停止，由人处理本地修改、未推送提交或分支差异；安装程序不得自动 stash 或覆盖。

运行回归：

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s Tools/task-ledger/tests -p 'test_*.py'

验收以退出码 0、全部测试 OK 和 validate=true 为准，不把历史测试数量写死为产品指标。

15. 注册来源和设备

python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> source-list
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> device-list
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> registry-validate

新设备登记：

python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> device-register \
  --registry-device-id '<DEVICE_ID>' \
  --label '<DEVICE_LABEL>' \
  --kind computer \
  --event-id 'registry:device:<DEVICE_ID>:v1' \
  --origin user \
  --device-id '<CURRENT_DEVICE_ID>'

同一设备的新 ComputerName 使用 device-alias，不要重复注册为另一台物理设备。未知来源/设备不会阻断历史兼容写入，但会被注册校验报告，必须在交付前说明或治理。

16. 安装顺序

1. 记录器：sync、validate、测试；
2. 注册表：来源和设备可解析；
3. Codex：合并 Hook 和 AGENTS；
4. Claude App：合并 settings 和 CLAUDE；
5. Hermes：安装后合并 config 和 SOUL；
6. 每端分别真实冒烟；
7. 目标设备间 Git 同步验收。

用户级配置不在 AI_OS Git 中，每台电脑都要单独备份、安装、重启、授权和验收。

17. 配置备份

修改前创建时间戳备份。若文件不存在，只创建对应目录，不制造空备份：

backup_stamp=$(date +%Y%m%d-%H%M%S)
test ! -f ~/.codex/hooks.json || cp ~/.codex/hooks.json ~/.codex/hooks.json."$backup_stamp".bak
test ! -f ~/.codex/AGENTS.md || cp ~/.codex/AGENTS.md ~/.codex/AGENTS.md."$backup_stamp".bak
test ! -f ~/.claude/settings.json || cp ~/.claude/settings.json ~/.claude/settings.json."$backup_stamp".bak
test ! -f ~/.claude/CLAUDE.md || cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md."$backup_stamp".bak
test ! -f ~/.hermes/config.yaml || cp ~/.hermes/config.yaml ~/.hermes/config.yaml."$backup_stamp".bak
test ! -f ~/.hermes/SOUL.md || cp ~/.hermes/SOUL.md ~/.hermes/SOUL.md."$backup_stamp".bak

只合并账本条目，保留客户已有 MCP、权限、模型、提示词和其他 Hook。回滚只恢复本次配置变更；已经产生的 v2 事件不删除，通过纠正事件处理。

18. 客户端安装位置

完整配置见下一篇。所有 Hook 命令使用真实绝对路径；Hermes 不经过 shell 展开，不能依赖 ~ 或 $HOME。

19. 跨设备切换

离开设备 A 前：更新状态与证据、validate、查看 Git 范围、只提交相关事件和交付物。只有收到明确推送指令或约定的离机动作时才 pull/push。

设备 B：先看工作区，git pull --ff-only，再 sync、validate，确认本机用户级 Hook 和设备身份，最后继续任务。若绑定任务在另一设备活跃，必须完成 handoff，不能绕过门禁。

20. 安装完成定义

配置文件存在只是 L1。真正“安装成功”至少需要：客户端发现 Hook、命令已授权、实质请求进入待开始、首次工具进入进行中、Agent 结束进入待验证、用户确认进入已完成、来源设备正确、validate 为 true。双设备产品还必须在目标机 pull + sync 后看到同一任务轨迹。

21. 共用规则

把 <AI_OS_ROOT> 替换为客户机真实绝对路径。已有配置只能合并，不能整文件覆盖。每条命令的 TASK_LEDGER_ROOT 必须显式设置，不能依赖适配器中的开发机默认值。

22. Codex

安装位置：~/.codex/hooks.json。

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/codex_hook.py user-prompt",
        "timeout": 5
      }]
    }],
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/codex_hook.py pre-tool",
        "timeout": 5
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/codex_hook.py stop",
        "timeout": 5
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/codex_hook.py session-end",
        "timeout": 5
      }]
    }]
  }
}

校验 jq empty ~/.codex/hooks.json，完全重启 Codex，使用 /hooks 查看并信任四个事件。JSON 合法只证明语法，不能证明客户端已加载。

23. Claude App / Claude Code

Claude App 是本方案主要使用入口。它的内置 Claude Code 运行时与 CLI/IDE 共用 ~/.claude/settings.json。内部来源统一为 claude，不因入口不同拆分来源。

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/claude_hook.py user-prompt",
        "timeout": 5
      }]
    }],
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/claude_hook.py pre-tool",
        "timeout": 5
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/claude_hook.py stop",
        "timeout": 5
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/claude_hook.py session-end",
        "timeout": 5
      }]
    }],
    "TaskCompleted": [{
      "hooks": [{
        "type": "command",
        "command": "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/claude_hook.py task-completed",
        "timeout": 5
      }]
    }]
  }
}

校验 jq empty ~/.claude/settings.json，完全退出并重启 Claude App。真实验收必须至少覆盖 UserPromptSubmit、PreToolUse、Stop；再从项目子目录结束一次任务，确认根项目任务能进入待验证。若模型请求返回 401，应单独修复登录；OAuth 失败与 Hook 是否触发是两条证据链。

24. Hermes Agent

安装位置：~/.hermes/config.yaml。Hermes 按参数拆分命令，不做 shell 展开；必须使用绝对路径。

hooks:
  pre_llm_call:
    - command: "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/hermes_hook.py pre-llm"
      timeout: 5
  pre_tool_call:
    - command: "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/hermes_hook.py pre-tool"
      timeout: 5
  post_llm_call:
    - command: "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/hermes_hook.py post-llm"
      timeout: 5
  on_session_start:
    - command: "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/hermes_hook.py session-start"
      timeout: 5
  on_session_end:
    - command: "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/hermes_hook.py session-end"
      timeout: 5
  on_session_finalize:
    - command: "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/hermes_hook.py session-finalize"
      timeout: 5
  on_session_reset:
    - command: "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/hermes_hook.py session-reset"
      timeout: 5
  subagent_stop:
    - command: "/usr/bin/env TASK_LEDGER_ROOT=<AI_OS_ROOT> /usr/bin/python3 <AI_OS_ROOT>/Tools/task-ledger/adapters/hermes_hook.py subagent-stop"
      timeout: 5
hooks_auto_accept: false

当前适配器还支持可选 subagent_start，但它不属于历史 8/8 验收范围。保持 hooks_auto_accept: false，逐项审阅，运行 hermes hooks list、hermes hooks doctor 和三个核心事件测试。非交互 Gateway 不能弹出首次授权时，应先在交互 CLI 完成授权。

25. 可复制的 v2 账本提示词

Codex 安装到 ~/.codex/AGENTS.md，Claude 安装到 ~/.claude/CLAUDE.md。Hermes 由 PreLlmCall 动态注入任务上下文，SOUL.md 至少保留证据、状态、隐私和 Git 边界。

## 跨项目任务账本（全局，v2）

每次用户消息由客户端 Hook 写入本机候选审计。Hook 可以用轻量规则把简单、明确、可执行的请求登记为“待开始”；确认、闲聊、纯提问和已拒绝事项不形成正式任务。

- 收到候选上下文后，按语义识别独立原子任务；误登记、复合需求和近义重复由当前 Agent 使用账本 CLI 纠正。
- 来源表示客户端而非触发者：Codex 为 `codex`，Claude App / Claude Code 为 `claude`，Hermes Agent 为 `hermes`；不得改写为 `automation` 或 `user`。
- `--project` 使用真实 cwd。跨 Mac 项目身份会把 `/Users/<用户名>/...` 归一为同一相对项目。
- 同会话的同义改述、修正、追问和补充必须续办原任务，并把新增内容追加为“补充需求”；不得新建近义任务。
- 只有独立可验收事项才新建任务。关系不确定时不新建、不完成前项，先结合完整对话判断。
- 第一次工具调用后应进入“进行中”；实现完成但尚未人工验收时进入“待验证”。
- Agent 在项目子目录结束时可收口根项目任务，但结构化任务 ID、会话和祖先项目关系必须匹配。
- 同会话明确验收完成最近的待验证任务；确认开启独立新任务时，完成最近的待验证或进行中前项；阻塞和跨会话任务不自动完成。
- 状态只使用：待开始、进行中、待验证、已完成、阻塞。已完成必须有文件、命令、测试、提交号、链接或明确验收等证据。
- 权威主数据是 `Tasks/Ledger/events/` 不可变事件分片。SQLite、日报和生成状态页是本机缓存或视图；`task-ledger.sync.json` 是 v1 遗留文件。
- 正式任务目标和证据会进入 Git。不得写入密钥、密码、Token、Cookie 或不应同步的隐私原文。
- 项目自己的任务文件和 STATUS 仍需遵守；全局账本补充而不替代项目记录。

## 双设备账本与 Git（v2）

- 使用稳定设备 ID。显式 `--device-id` 优先，其次是 `TASK_LEDGER_DEVICE` 和 macOS ComputerName。
- 开始工作前在 AI_OS 根目录执行 `git pull --ff-only`；失败时停止，不自动 stash、覆盖或强行合并。
- 拉取后运行 `python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> sync` 和 `validate`。
- 交付时只暂存本任务事件、任务卡和确认交付物；不得捎带其他修改。
- 本地提交、远端 push、另一设备验收分别记录。只有用户明确要求时才 push；Hook 不执行 Git 网络操作。

26. 通用系统提示词建议

账本协议之外，建议统一要求：主要任务先复述确认；事实断言附证据；不确定写“待补充”；开发任务更新项目任务卡和 STATUS；测试、构建、部署、人工验收分别记录；最终答复包含任务编号、状态、交付物、验证和下一步。

通用规范可以按客户管理制度调整，但不能删除五态、完成证据、同会话复用、来源/设备语义、隐私边界和禁止 Hook 自动 push 等核心约束。

27. 每日开始

cd <AI_OS_ROOT>
git status --short --branch
git pull --ff-only
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> sync
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> validate

确认工作项目、当前客户端和设备。sync_file=null 在 v2 是正常现象；它表示没有继续写 v1 同步索引，不代表丢失数据。

28. 收到需求

1. 排除确认、闲聊、纯提问、单独编号和已拒绝事项；
2. 把能独立验收的事项拆成原子任务；
3. 判断同会话最近任务是同一、独立还是不确定；
4. 同一任务续办并追加补充；独立事项登记新任务；
5. 说明本轮目标，但不把“已登记”说成“已完成”。

自动轻量规则不是完整语义模型。Agent 仍需发现漏建、误建和复合需求，使用 CLI 显式纠正。

29. 执行与阶段回写

首次工具调用后应进入进行中。每次完成阶段、运行测试、出现风险、需要决策或准备交付时，记录文件、命令、结果、提交或链接。未知信息写“待补充”。

Agent 完成自己的工作时进入待验证；若缺登录、授权、外部数据或客户决定，则进入阻塞。不能因为模型输出“完成”就跳过人工验收。

30. 交付与关闭

关闭前核对目标、验收标准、证据和风险。用户在同一会话明确验收后，最近待验证任务可转已完成；用户确认开启一个独立新任务时，最近待验证或进行中前项可完成。阻塞任务、跨会话旧任务和关系不确定的任务不得自动关闭。

最终交付说明：任务编号、当前状态、文件路径、验证结果、未验证项、本地提交、是否 push、下一步。

31. 动态统计

来源和设备数量不能写死。临时统计可从快照聚合：

python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> snapshot | \
jq '.events | sort_by(.origin) | group_by(.origin) |
  map({source: .[0].origin, events: length,
       tasks: (map(.task_id) | map(select(. != null)) | unique | length)})'

设备把 .origin 替换为 .device_id；矩阵使用 group_by([.origin, .device_id])。这些命令按历史原值统计，规范实体和异常另看 snapshot.registry 或 registry-validate。FR-19 完成前，不把临时 jq 输出宣传为正式管理后台。

32. 验收矩阵

33. 标准冒烟

在隔离目录发出：“创建一个只包含当前日期的 smoke-test.txt，读取确认后汇报，先不要标记已完成。”检查：

1. 用户消息后出现待开始任务；
2. 第一次工具调用进入进行中；
3. 最终回复提供文件和读取证据；
4. Stop 后进入待验证；
5. 补充一句要求，任务不重复并出现补充需求；
6. 用户开启独立新任务，最近前项完成；
7. 阻塞项不因新任务完成；
8. 来源和设备与真实环境一致；
9. 用户验收后才完成。

34. 常见故障

34.1 缺少 --root

--root 是顶层参数，必须写在子命令前：task_ledger.py --root <AI_OS_ROOT> validate。

34.2 配置正确但 Hook 未触发

依次检查配置所在 Home、绝对路径、Python 可执行性、客户端重启、Hook 列表、信任/allowlist、超时和 stderr。直接适配器探针只能证明适配器，不代替真实客户端。

34.3 Claude 一直待开始

检查 ~/.claude/settings.json 是否包含 PreToolUse。若 Claude App 先报 401，重新登录后再测真实工具调用；不要把认证故障写成 FR-03 失败。

34.4 Claude App 最终仍在进行中

检查 Stop 候选 cwd、结构化任务 ID 和会话。新版允许任务项目是 Stop cwd 的祖先，但不允许兄弟项目、跨项目或跨会话。结构化标记未匹配时应有 stderr，而不是静默成功。

34.5 webui 与 user

两者不是同一来源。webui 是任务看板应用，user 是人工直接管理入口。只有确认是拼写或历史别名时才通过 source-alias 归一。

34.6 设备多名

新 ComputerName 属于同一物理设备时添加别名；真正的新电脑才注册新设备。历史事件保持不可变，不做批量替换。

34.7 validate-links 为 false

主账本 validate=true 与双链存在历史 missing 可以同时发生。逐项说明，不把双链缺口误写成 Hook 安装失败，也不声称全部健康。

35. 安全和恢复

Hook 以当前用户权限运行，按可执行代码审阅；不在任务字段保存凭据；不自动 Git 网络操作；不修改既有事件分片；修改用户配置前备份；演示和支持日志脱敏。

缓存或视图异常先保存现状，再从事件运行 sync。配置回滚不删除已经生成的正式事件；错误业务状态用新的纠正事件表达。

36. 产品包组成

标准交付包括任务账本代码、三端配置模板、系统提示词、需求/架构/安装/运维文档和验收记录模板。可选实施包括客户机安装、历史迁移、设备命名治理、项目双链、培训和维护。

这是一套本地优先的软件与实施方案，不天然等于托管 SaaS。许可证、设备数、维护期、SLA、价格、退款和二次分发必须在合同中明确，不能由技术白皮书替代。

37. 交付套餐建议

FR-19 产品化统计页、团队权限和云端 API 属于新增范围，不应默认包含在 v2 标准版。

38. 客户环境表

39. 实施责任分工

交付方负责：提供受支持版本、配置合并说明、真实冒烟、证据记录和已知限制。客户负责：第三方账号和 OAuth、Git 权限、设备访问、密钥安全、仓库访问控制、敏感任务规范和最终验收。

第三方客户端或模型服务升级可能改变 Hook 行为。支持期内先复现并判断是产品缺陷、环境问题还是新增需求，不把所有 401、网络和登录故障都归为账本缺陷。

40. 隐私与法律边界

候选原文默认留在本机 SQLite，但正式任务的目标、证据、项目路径和部分会话元数据会进入 Git 事件。客户应控制仓库访问权限，并规定哪些业务内容不得进入正式任务。

交付演示使用隔离数据。若支持过程需要获取日志或配置，应先脱敏并取得授权。许可证、隐私条款、责任限制和合规声明应由专业法律人员审阅；本文只提供实施建议。

41. 上线和维护

上线前冻结交付提交号，记录各客户端版本和验收结果。第三方客户端升级时，先在非关键设备回归：Hook 列表、三阶段流转、同会话补充、前项完成、阻塞保护、来源设备和 validate。

支持请求分类：

• 产品缺陷：受支持版本可复现；
• 环境问题：登录、权限、网络、客户端配置；
• 新需求：新来源、统计后台、团队服务、云端桥接；
• 使用咨询：提示词和 SOP 执行问题。

42. 对外演示脚本

1. 用 Codex 或 Claude App 创建隔离任务；
2. 展示第一次工具调用自动进入进行中；
3. 补充需求，展示同一任务不重复；
4. 展示 Agent 结束只到待验证；
5. 用户发起独立新任务，最近前项完成；
6. 切换客户端或设备，展示参与来源/设备；
7. 展示不可变事件、任务卡和注册表；
8. 解释本地测试、真实客户端、人工验收和跨设备验收的差别。

演示重点是“可信交付”，不要展示真实客户任务，也不要把 FR-19 规划功能包装为现成管理后台。

43. 路线图

可选后续版本：规范化来源/设备统计层、来源 × 设备矩阵、日报周报聚合、Web 管理页、客户级导入导出、敏感字段策略、服务端 API/MCP、团队身份与权限。每项应独立编写需求、测试和商业范围。

A. 最小任务卡

# TASK-时间戳：任务标题

- 状态：待开始 / 进行中 / 待验证 / 已完成 / 阻塞
- 项目：<PROJECT>
- 创建来源：<SOURCE>
- 参与来源：<SOURCES>
- 创建设备：<DEVICE>
- 参与设备：<DEVICES>

## 目标

一句话描述可验收结果。

## 补充需求

- 后续同会话新增要求。

## 证据

- 文件：<PATH>
- 命令：<COMMAND>
- 结果：<RESULT>
- 提交/链接：<COMMIT_OR_URL>

B. 常用 CLI

# 重建和校验
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> sync
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> validate
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> validate-links
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> registry-validate

# 来源和设备
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> source-list
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> device-list

# 当前会话任务
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> active \
  --project '<PROJECT>' --session-id '<SESSION_ID>' --limit 20

登记任务：

python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> register \
  --event-id '<SOURCE>:<SESSION>:<TURN>:register' \
  --origin '<SOURCE>' \
  --session-id '<SESSION>' \
  --turn-id '<TURN>' \
  --project '<PROJECT>' \
  --title '<TITLE>' \
  --goal '<GOAL>' \
  --status '待开始' \
  --device-id '<DEVICE_ID>'

续办和追加补充：

python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> continue \
  --task-id '<TASK_ID>' \
  --event-id '<SOURCE>:<SESSION>:<TURN>:continue' \
  --origin '<SOURCE>' \
  --session-id '<SESSION>' \
  --turn-id '<TURN>' \
  --device-id '<DEVICE_ID>' \
  --note '<NOTE>' \
  --supplement '<ADDITIONAL_REQUIREMENT>'

状态流转：

python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> transition \
  --task-id '<TASK_ID>' \
  --status '待验证' \
  --event-id '<SOURCE>:<SESSION>:<TURN>:transition' \
  --origin '<SOURCE>' \
  --session-id '<SESSION>' \
  --turn-id '<TURN>' \
  --device-id '<DEVICE_ID>' \
  --evidence '<FILES_COMMANDS_RESULTS>'

C. v1 升级 v2

升级前备份仓库和本机 SQLite，确认工作区边界。按版本实际帮助输出核对参数：

python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> migrate-v2 --dry-run
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> migrate-v2
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> validate
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> cutover-v2
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> sync
python3 Tools/task-ledger/task_ledger.py --root <AI_OS_ROOT> validate

切换前如果 v1/v2 投影不一致，工具应拒绝切换。不要删除 v1 历史文件来绕过检查。

D. 客户验收记录

# AI 任务账本客户验收

- 客户：<CUSTOMER_NAME>
- 交付版本：v2.0
- AI_OS 提交：<COMMIT>
- 设备：<DEVICE_ID>
- 客户端：<CLIENT>
- 使用入口：Desktop / CLI / IDE / Gateway
- 实施日期：<DATE>

## 验证

- [ ] 配置文件语法正确
- [ ] 客户端发现并授权 Hook
- [ ] 实质请求进入待开始
- [ ] 第一次工具调用进入进行中
- [ ] Agent 结束进入待验证
- [ ] 同义改述/补充复用原任务
- [ ] 独立新任务完成最近前项
- [ ] 阻塞项不自动完成
- [ ] 用户验收后进入已完成
- [ ] 来源和设备正确
- [ ] validate 为 true
- [ ] 跨设备 pull + sync 通过（如合同包含）

## 结论

- 状态：待验证 / 已完成 / 阻塞
- 证据：<EVIDENCE>
- 阻塞：<BLOCKERS>
- 验收人：<ACCEPTOR>

E. 日终检查

• 当天重要交办均形成正式任务；
• 近义补充没有重复建卡；
• 待验证和阻塞原因清楚；
• 已完成均有证据；
• 候选 SQLite 未加入 Git；
• 没有暂存无关修改；
• 用户未授权时没有 push；
• 客户机验收与本地测试分开记录。

F. 术语