hunjing/docs/delivery/implementation-roadmap.md

# 完整 1.0 实施 TODO

> 本清单中的全部条目都属于同一个 1.0。工作包可以并行开发和独立验收，但不能作为残缺 1.0 对外发布。

## 使用规则

- `[ ]` 表示 1.0 未完成，不表示推迟到后续版本。
- 完成条目时附实现位置、真实调用点、自动化测试和运行证据。
- 没有调用点的定义、只有页面没有后端闭环、假数据、`TODO`、`pass` 和省略实现均不能勾选。
- 所有工作包和 `product/complete-1.0-scope.md` 发布门完成后才能标记 1.0。

## WP-01 工程、契约与身份

- [ ] 建立 Next.js、FastAPI、Tauri v2、Worker 和统一 Makefile 工程。
- [ ] 建立 OpenAPI 3.1 单一真源和 TypeScript/Rust client 生成。
- [ ] 实现 RFC 9562 ID 生成与校验：持久化资源使用 UUIDv7，请求/Trace record 使用 UUIDv4，秘密与 capability 使用 CSPRNG opaque value。
- [ ] 实现 `api.* /v1` Native API 与 `gateway.*` 双兼容入口分面。
- [ ] 实现 OAuth 2.1、Web Session Cookie、Tauri PKCE、公共 Bearer 和 Service Account API key。
- [ ] 实现 Header-only 凭据、CSRF、Origin、scope、轮换、撤销和重用检测。
- [ ] 实现用户、多凭证、Session、PersonalDomain 和设备注册。
- [ ] 实现私箧：用户独立持钥加密区，平台仅存密文不可恢复；账户恢复、管理员与诊断均不可读（ADR-021）。
- [ ] 实现 RBAC/ABAC、资源归属校验和跨域失败关闭。
- [ ] 实现 W3C Trace Context、结构化日志、审计和 Outbox。
- [ ] 实现 PostgreSQL 基线与 Alembic 迁移（开发/测试/自托管/正式统一，ADR-024；测试不使用 SQLite 替代）。
- [ ] 验证跨用户、跨角色、跨 Workspace IDOR 测试。

## WP-02 角色、导入与可携

- [ ] 实现 Character、CharacterVersion、关系和来源谱系。
- [ ] 实现手动、模板、角色卡静态导入和安全预览。
- [ ] 实现随缘：按偏好生成匿名灵胚候选与审阅，不抽卡、不分配已有主体。
- [ ] 实现现实人物授权治理：仅本人或可验证授权可创建，已故现实人物不开放。
- [ ] 实现角色社区 Fork，保留来源、许可和版本边。
- [ ] 实现角色人格/关系变化候选和审核。
- [ ] 实现内驱力维度：声明式动机数据、用户审阅编辑与版本化。
- [ ] 实现大周天循环（ADR-023）：`BigCycle`（`cycle_`）聚合根、阈值触发与逐角色频率上限、四阶段评估（回顾/对照/提议/提交）、阶段记忆 `_phase_memory`、受托后台 Run 执行；产出人格/关系/世界认知/次生目标候选，演化以版本谱系留痕；用户可关闭并可见每次输入、产物与费用。
- [ ] 实现角色、设定、记忆、对话、资产和来源导出。
- [ ] 验证导入物不能执行脚本、注册工具或覆盖现有角色。

## WP-03 多模态分支对话

- [ ] 实现 Conversation、Branch、Message、引用锚和当前路径。
- [ ] 实现统一 ContentBlock 与 Markdown→canonical block 规范化，覆盖 Markdown、代码、数学公式、Mermaid、图片、视频、音频、文件、工具状态和产物。
- [ ] 实现文字、图像、视频、音频、文件和混合消息。
- [ ] 实现 Block 级 SSE started/delta/progress/completed/failed、重放、去重、对账、中断、取消和错误事件。
- [ ] 实现 Web/Tauri 的 Markdown、Shiki、KaTeX、Mermaid、媒体分级实时渲染与安全净化。
- [ ] 实现重生成、编辑版本、候答比较和分支移植。
- [ ] 实现分支对话交互态：临时芽体、残答封存、续生新节点、引用合流、结题与复照、回响接纳和上下文镜（见统一富内容协议第 9 节）。
- [ ] 实现三界与归真作用域：真界/境界/幻境、`canonical_scope` 携带与保留、入境/出境可见、言可入幻行必归真（ADR-020）。
- [ ] 实现上下文压缩和 Context Manifest。
- [ ] 验证分支隔离、流中断和恢复不伪装完成。

## WP-04 记忆、知识与检索

实现边界与验收以[记忆与知识架构](../architecture/memory-and-knowledge.md)为准。

- [ ] 实现显式记忆与异步自动 MemoryCandidate，按来源 hash 和 extractor version 幂等。
- [ ] 大周天评估作为 MemoryCandidate 来源，携带 `big_cycle` 标记并复用审核流转与幂等。
- [ ] 实现归真作用域记忆：境界只成世界知识候选、幻境手动入忆标注性质；白名单低风险内容自动写入并附撤销窗。
- [ ] 实现角色完整生命周期：静修、归藏（隐藏可恢复）与复照（重开不抹历史）、死亡（冷静期、告别、只读档案、继承承接，与数据删除分离）、铸魂（重大重塑强确认）与初照自陈。
- [ ] 实现 Personal Domain/Workspace 二选一所有权、Character 约束和子 Agent 默认只读快照。
- [ ] 实现 `fact`、`preference`、`event`、`relationship` 类型及来源、敏感度、置信度和有效期。
- [ ] 实现 Candidate 审批与不可变 MemoryVersion；批准事务同时写 Audit 与 Outbox。
- [ ] 实现 ETag 并发纠正、取代、恢复、衰减候选、归档、删除墓碑和删除传播。
- [ ] 实现 KnowledgeDocument、世界实体和结构化关系；知识与人物经历分离。
- [ ] 实现授权/状态预过滤后的 PostgreSQL 全文、pgvector 语义和结构化检索；保留可替换端口。
- [ ] 实现 ContextSnapshot 中的召回证据、token/延迟预算、降级原因和用户可见来源。
- [ ] 实现索引重建、重复/乱序 Outbox 和删除优先 fail-closed。
- [ ] 建立中文、多角色、分支、时间、冲突和多跳评测基线，并固定数据集、模型与检索配置。
- [ ] 验证跨用户/角色/Workspace/Conversation/Branch/Run 与已删/过期/撤权/被取代内容召回率为 0；来源 Prompt Injection 和插件输出不能扩大 scope；每个入选项可追溯到当前版本与来源。

## WP-05 模型网关与运行观测

- [ ] 实现 OpenAI-compatible 与 Anthropic Messages 适配器。
- [ ] 实现逻辑模型、能力目录、Endpoint、路由、重试和故障转移；模型配置继承链（平台硬边界 → 平台目录 → 用户偏好/BYOK → 角色覆写 → 会话临时选择）上层不可被下层覆盖。
- [ ] 实现首个可见 delta 后禁止切换 Provider。
- [ ] 实现 Prompt Cache 规划和供应商 usage 标准化。
- [ ] 持久化 Run、Turn、ModelCall、token、cache、TTFT、成本和错误。
- [ ] 实现小周天闭环完成信号：Run 完成时记录归真引用、候选引用、token/费用与时间窗，作为大周天触发的唯一输入面（ADR-023）。
- [ ] 实现价格版本、预算、配额和限流。
- [ ] 实现普通观测与双重授权诊断接口。
- [ ] 验证未知 usage 为 null、OpenAI cache token 不重复计数。

## WP-06 Agent、工具与多 Agent

- [ ] 实现 Agent Definition、Run/Turn 状态机和事件流。
- [ ] 实现计划、RunBudget、暂停、继续、取消和结果验收。
- [ ] 实现内置工具、MCP、Skill 和 Tool Registry。
- [ ] 实现 Schema 校验、Policy、确认、幂等和 ToolCall 诊断。
- [ ] 实现 Coordinator、ChildRun、并行调度和结构化 Handoff。
- [ ] 实现深度、并发、token、费用、时间和权限硬上限。
- [ ] 实现 Sandbox Worker，缺少隔离时 fail closed。
- [ ] 验证子 Agent 权限单调收窄和副作用不重复执行。

## WP-07 插件 SDK、Runtime 与 Registry

- [ ] 实现全部插件类型的统一 Manifest 和 API version。
- [ ] 实现 contribution、typed hook、reversible effect 和依赖注入。
- [ ] 实现 Run PluginSnapshot、drain、停用、升级和回滚。
- [ ] 实现声明式/远程插件受限 Runtime。
- [ ] 实现可信本地代码插件的独立进程/容器 Runtime。
- [ ] 实现 TypeScript/Python SDK、模拟 Host、测试与打包工具。
- [ ] 实现 Registry、签名、扫描、审核、举报、撤架和兼容性。
- [ ] 实现插件搜索、安装、权限确认、启停、升级和卸载。
- [ ] 实现 UI 扩展隔离和消息协议。
- [ ] 验证购买/安装不自动启用或授予新权限。

## WP-08 语音、多语言与图像

- [ ] 实现 ASR、TTS、语言检测、字幕和多语言对话。
- [ ] 实现 WebSocket 实时语音、打断、弱网和取消。
- [ ] 实现声音预设、原创设计、授权克隆和撤回。
- [ ] 实现文生图、图生图、局部重绘、分层和角色一致性。
- [ ] 实现媒体任务、进度、取消、重试、来源和许可。
- [ ] 实现界面国际化、时区、数字、货币和 RTL 基础能力。
- [ ] 验证声音/肖像授权、媒体删除和多语言安全策略；原音频短期缓存、转写正影并存、多说话者匿名分段与声纹独立同意；关闭全部多模态后文字相伴完整可用。

## WP-09 Live2D 与 3D

- [ ] 实现 Cubism-compatible 导入、校验、参数/表情/物理/动作映射。
- [ ] 实现 Live2D 分层辅助、可视化编辑、预览、运行和导出。
- [ ] 实现 VRM/glTF 导入、验证和标准化。
- [ ] 实现 3D 材质、纹理、骨骼、表情、动作和附件编辑。
- [ ] 实现场景、灯光、相机、环境和动画状态编辑。
- [ ] 实现 Web/Tauri Live2D 与 3D Runtime 和标准导出。
- [ ] 实现资产命令历史、版本、来源和许可。
- [ ] 验证弱设备降级、资源上限和恶意模型文件。

## WP-10 Web、桌面、移动与感知

- [ ] 实现响应式 Web 的全部核心功能。
- [ ] 实现 Tauri v2 桌面应用、更新、存储和安全 Capability。
- [ ] 实现 Tauri v2 iOS/Android 应用和平台签名发布。
- [ ] 实现文件、相机、麦克风、屏幕、位置和通知能力。
- [ ] 实现 DeviceGrant、采集指示、期限、暂停、撤销和删除。
- [ ] 实现加密离线缓存和联网恢复；不创建独立角色副本。
- [ ] 验证平台权限、后台限制、丢失设备撤权和本地数据清除。

## WP-11 完整社区与角色社区

- [ ] 实现用户主页、关注、屏蔽和可见性。
- [ ] 实现动态、作品、评论、回复、点赞、收藏、标签和分享。
- [ ] 实现角色、世界、知识、工作流、媒体和插件发布页面。
- [ ] 实现搜索、话题、趋势、推荐、推荐解释和重置。
- [ ] 实现举报、审核、年龄分级、限流、移除和申诉。
- [ ] 实现来源、署名、许可、Fork 谱系和下架传播。
- [ ] 实现通知和创作者安全工具。
- [ ] 验证私密角色数据不会进入社区发布物或推荐特征。

## WP-12 协作空间

- [ ] 实现 Workspace、成员、邀请和 RBAC。
- [ ] 实现角色、世界、知识、工作流和资产的分支与版本。
- [ ] 实现评论、评审、批准、合并和活动记录。
- [ ] 实现文本/场景协同编辑与冲突处理。
- [ ] 分离编辑、发布、市场上架和财务权限。
- [ ] 验证成员移除、链接泄露、并发覆盖和跨 Workspace 访问。

## WP-13 市场、支付与结算

- [ ] 实现免费/付费 Listing、版本、许可、地区、税类和交付摘要。
- [ ] 实现购物车或直接购买、Order/OrderItem 和价格快照。
- [ ] 集成支付 Provider 与客户端确认流程。
- [ ] 实现 Webhook 验签、时间窗、乱序和幂等处理。
- [ ] 实现 Refund、Dispute、Entitlement 和下载/更新策略。
- [ ] 实现不可变 Ledger、平台费、创作者应付、税、准备金和冲正。
- [ ] 实现 CreatorBalance、SettlementBatch、PayoutAttempt 和对账单。
- [ ] 实现 KYC/税务/发票 Provider 引用和创作者结算设置。
- [ ] 实现每日支付/订单/Ledger/结算自动对账。
- [ ] 验证金额篡改、重复付款、重复退款、拒付和结算失败恢复。
- [ ] 实现保全态与计费伦理：欠费/封禁只读保全不删数据；不按记忆、感情或亲密计费；BYOK 不重复计费（ADR-021）。

## WP-14 运营、自托管与发布收口

- [ ] 实现管理面、支持工单、脱敏支持包和诊断授权。
- [ ] 实现内容、插件、角色和市场治理队列。
- [ ] 实现 PostgreSQL、Redis、对象存储、Worker 和 Sandbox 部署。
- [ ] 实现个人单机与标准服务器 Docker Compose 自托管。
- [ ] 实现迁移、备份、恢复、删除重放和插件撤架演练。
- [ ] 实现 SLO、指标、告警、容量、成本和事故响应；验证 SLO 99.9%、RPO≤5 分钟、RTO≤1 小时目标与 PersonalDomain 区域驻留不跨区漂移。
- [ ] 完成富内容 XSS/URL/SVG/公式宏/资源耗尽、可访问性、国际化、弱网、性能和跨端测试。
- [ ] 验证双层文化名在导航、状态、审批、设备和交易界面同时提供直白解释，且未进入稳定协议值。
- [ ] 完成隐私、社区规范、版权、支付、退款、结算和税务决策。
- [ ] 生成每条需求到实现、调用点、测试和运行证据的发布矩阵。
- [ ] 确认所有文档 TODO 和代码占位已关闭，正式标记 1.0。

## WP-15 灵台引擎与多语言绑定

实现边界与验收以[灵台引擎架构](../architecture/lingtai-engine.md)、[Lingtai C ABI](../contracts/lingtai-ffi.md)和 [Lingtai Service](../contracts/lingtai-service.md) 为准。

- [ ] 建立 C++23/CMake 工程与交叉编译矩阵，产出 `libhunjing` 动态/静态库与单一公共头。
- [ ] 实现 `hj_core`（太一总枢）：ABI/服务版本协商、句柄表、跨形态统一入口、Run/Turn 状态转换校验、事件 `sequence` 与错误上下文。
- [ ] 实现 `hj_transform`：Markdown → canonical ContentBlock 确定性解析、数学定界符与 Mermaid fenced 提取、parser version；含 fuzz。
- [ ] 实现 `hj_stream`：流事件编码、`delta_index`、去重键、节流与重放缓冲。
- [ ] 实现 `hj_policy`：分层递进的 Schema 子集校验、路径/URL 校验、HMAC 验签、幂等键规范化、决策表评估。
- [ ] 实现 `hj_plan`：计划 DAG 校验、RunBudget 核算、Context Manifest 裁剪排序。
- [ ] 实现 `hj_recall`：只读离线混合索引、重排打分与多路合并；索引删除与授权变化随宿主重建。
- [ ] 实现 Python（nanobind）、Rust（bindgen + 安全包装）、Go（cgo）官方绑定与发布物。
- [ ] 实现 `hunjing-lingtai-server` 独立服务形态：gRPC 契约、mTLS、限流/超时/背压、健康检查与审计。
- [ ] 实现宿主"引擎 Port"：进程内与服务两个实现可按部署配置切换，业务语义不变。
- [ ] 接入宿主真实调用点：WP-03 消息规范化与 SSE、WP-06 工具校验、WP-13 Webhook 验签、WP-10 离线检索。
- [ ] 建立 sanitizer、fuzz、ABI 快照与双形态 golden 一致性测试；验证引擎缺失或服务不可达时宿主 fail closed。

## 已确认 2.0 TODO

以下内容不属于 1.0，不得混入 1.0 完成判定：

- [ ] 评估并选定可复用的开源 3D 建模项目。
- [ ] 完善为网格、雕刻、拓扑、绑定和专业动画完整建模器。
- [ ] 实现 LLM 对完整 3D 几何和绑定的可验证修改。
- [ ] 设计 IoT、机器人和物理动作控制安全边界。