📝 docs: 建立魂镜完整 1.0 设计文档体系

- 产品层：产品宪章与永久禁域、产品定义、完整 1.0 范围与发布门、道家文化语言体系、指标与反指标
- 研究层：参考项目研究（deepseek-harness、pi、MemOS、模型网关）、灵台原生引擎研究（业界原生引擎架构理念与道家文化出处）
- 架构层：系统、Agent 运行时（周天体系）、插件系统、灵台引擎（C++ 双形态）、媒体与设备、社区协作市场、前端富内容渲染、数据、记忆与知识
- 契约层：协议与稳定标识、API 总体约定、Native API、兼容网关、实时与 Webhook、内部端口、统一 ContentBlock 与流式（含分支对话交互态）、灵台 C ABI 与 gRPC Service、API 表面、HTTP 与事件、运行观测
- 决策：ADR-001 至 ADR-023（模块化单体、每 attempt 持久化、候选记忆、OAuth 2.1、灵台引擎、双形态部署、大周天演化、宪章、三界作用域、私箧与保全态、叩心、周天统一等）
- 交付：WP-01 至 WP-15 实施 TODO 与设计阶段交接文档
- 工程：AGENTS.md 工程规则（含 C++/灵台规范）、CLAUDE.md 引用、.gitignore

AGENTS.md

@@ -0,0 +1,263 @@
+# Hunjing 工程规则
+
+> 目标：交付可维护、可验证、可长期负责的完整 1.0。
+> 语言：用户可见输出、文档、注释和 Git Commit 使用简体中文；代码标识符和稳定协议值使用英文。
+
+## 1. 事实源与工作方式
+
+### 1.1 开发前阅读
+
+按任务读取对应文档，不凭旧设计或记忆实现：
+
+1. `docs/product/product-charter.md`：产品宪章、不可侵犯边界与永久禁域（上位约束）；
+2. `docs/product/product-definition.md`：产品定义与 1.0/2.0 边界；
+3. `docs/product/complete-1.0-scope.md`：完整 1.0 范围与发布门；
+4. `docs/product/cultural-language.md`：文化名、直白解释与工程映射；
+5. `docs/architecture/`：系统、Agent、插件、数据、媒体、社区市场和前端渲染架构；
+6. `docs/contracts/`：API、ContentBlock、事件、ID、枚举、请求头和错误；
+7. `docs/security/security-and-diagnostics.md`：安全和受保护诊断；
+8. `docs/delivery/implementation-roadmap.md`：1.0 TODO 与验收证据。
+
+事实层级：产品范围 → ADR → 架构 → 契约/OpenAPI → 实现 → 测试与运行证据。下游不得静默覆盖上游；运行事实与文档不符时先记录偏差，再修正事实源或实现。
+
+### 1.2 需求处理
+
+- 需求明确：完整实现；需求有多种会显著改变产品/API/数据/安全的解释：先列选项并询问。
+- 普通命名、格式和等价技术细节由 AI 按既有规则直接决定，不把常规判断推给用户。
+- 多步骤任务先列编号流程和验证方式；只有需要用户决策时暂停。
+- 不总结或附和错误前提；先指出问题，再给修正方案并继续可执行部分。
+- 未请求不做；发现无关问题只报告，不顺手重构。
+
+### 1.3 实施原则
+
+- **最小实现**：在满足完整当前需求和安全边界前提下采用最少代码、依赖和服务。
+- **能力必达，技术按需**：1.0 产品能力是硬范围；数据库、语言、服务拆分和库按 ADR、官方资料、实测规模和维护成本选择，不为堆技术栈而部署。
+- **优先复用**：标准库 → 平台能力 → 已安装依赖 → 成熟依赖 → 最小自研。新增依赖前查官方文档、版本兼容、许可、维护状态和现有能力。
+- **删除废弃路径**：不为未发布实现保留兼容层；正式公共契约按弃用策略演进。
+- **模块化单体优先**：服务拆分须有独立扩缩容、故障域、数据/密钥边界、团队节奏或量化瓶颈证据。
+- **安全边界不简化**：认证、授权、租户隔离、审批、交易账、幂等、审计、秘密管理、文件/URL 校验和 Sandbox fail-closed 不得省略。
+
+## 2. 完整 1.0 约束
+
+- `docs/delivery/implementation-roadmap.md` 中全部 1.0 TODO 和发布门完成前，不得称为正式 1.0。
+- 产品宪章的永久禁域不可被实现、插件、管理员或自托管配置关闭；与宪章冲突的实现决定都是缺陷。
+- 内部工作包可以并行开发和验收，但不是独立公开版本。
+- 1.0 包含：角色与记忆、分支多模态对话、多 Agent、插件生态、实时语音、多语言、图像、Live2D、3D 运行编辑、Web/Tauri 桌面与移动、设备感知、完整社区、角色社区、协作空间、真实支付退款分成结算、运营和自托管。
+- 已确认 2.0：Blender 级完整建模器、LLM 直接修改完整 3D 几何/绑定、IoT/机器人/物理动作控制。不得把其他已列能力静默移出 1.0。
+- 文档 TODO 是真实待办；实现中的 `TODO`、`pass`、省略代码、假数据和无调用点定义不算完成。
+
+## 3. 文化语言与工程标识
+
+- 产品使用完整双层文化体系：文化名 + 直白中文解释；首次出现和高风险界面必须显示直白解释。
+- API、OpenAPI、数据库、代码目录、事件、错误码、权限 scope、指标和日志只使用 `docs/contracts/` 登记的中性英文稳定值。
+- 后端返回 `status: "running"`，前端本地化为“运转 · 运行中”；不得把文化名作为唯一协议值。
+- 权限、金额、退款、删除、支付、结算、审核和现实后果不得用文化叙事掩盖。
+- 新文化名先更新 `docs/product/cultural-language.md`；新稳定值先更新契约/OpenAPI。
+
+## 4. API 与数据契约
+
+### 4.1 API 分面
+
+- Native：`api.<domain>/v1`；
+- OpenAI-compatible：`gateway.<domain>/openai/v1`；
+- Anthropic-compatible：`gateway.<domain>/anthropic/v1`；
+- Provider Webhook：`api.<domain>/webhooks/v1`；
+- Lingtai C ABI：进程内 `hj_*` 稳定符号，契约见 `docs/contracts/lingtai-ffi.md`；Lingtai gRPC Service：独立服务形态，仅限部署内部网络，契约见 `docs/contracts/lingtai-service.md`；两者为同一灵台引擎核心；
+- 内部模块优先用类型化 Port/Command/Query/Event，不为每个模块增加 HTTP。
+
+### 4.2 通用格式
+
+- OpenAPI 3.1 是公共 HTTP 契约单一真源；生成 TypeScript/Rust 客户端，不手写重复 DTO。
+- JSON/SQL/path 参数使用 `snake_case`；事件使用 `domain.action`；逻辑模型使用 `kebab-case`。
+- 时间为 UTC RFC 3339；时长为 `_ms` 非负整数；金额使用最小货币单位或 Decimal，禁止浮点。
+- 列表使用 opaque cursor；更新使用 ETag/`If-Match`；客户端忽略未知响应字段和枚举。
+- 创建 Run、支付、退款、结算和外部副作用必须使用 `Idempotency-Key`。
+- `Hunjing-Request-ID` 用于业务关联，`traceparent` 用于分布式追踪，两者不能互相替代。
+- 1.0 认证采用 OAuth 2.1：Web 使用安全 Session Cookie，Tauri 使用 Authorization Code + PKCE，公共客户端使用短期 Bearer，自动化使用限 scope Service Account API key。
+- 凭据只经 Header 传递，不进入 URL、query、业务 body、SSE data 或 WebSocket URL。
+- Provider Header deny-by-default，仅 Adapter 白名单透传；用户登录凭据、Cookie 和诊断令牌永不转发上游。
+
+### 4.3 消息与 Run
+
+- 聊天通过 `POST /v1/conversations/{id}/messages` 在同一事务创建 Message 和可选 Run；一个幂等键覆盖两者。
+- 后台任务通过 `POST /v1/runs` 显式创建。
+- Run → Turn → ModelCall/ToolCall 分层；每个上游 attempt 单独记录，不覆盖失败或重试。
+- 首个用户可见流事件前可以安全重试/故障转移；之后不得切换 Provider 重新生成另一份内容。
+
+### 4.4 数据
+
+- PostgreSQL/SQLite 关系数据是权威事实源；对象存储保存媒体；全文、向量、图投影、推荐特征和缓存均可重建。
+- 角色、消息、记忆、知识、社区发布、许可、订单、支付和 Ledger 分离建模。
+- Ledger 不可变，修正写反向分录；支付 Provider Adapter 不直接写账。
+- 删除传播到主存储、索引、缓存和派生数据；墓碑不保存被删原文。
+- 权威状态、AuditEvent 和 OutboxEvent 在同一事务提交。
+
+## 5. 统一 ContentBlock 与流式输出
+
+### 5.1 ContentBlock
+
+Native API 和持久化消息统一使用 `docs/contracts/content-blocks-and-streaming.md` 定义的类型化 Block：
+
+- `text`、`markdown`、`code`、`quote`、`table`、`callout`；
+- `math`、`mermaid`；
+- `image`、`video`、`audio`、`file`、`gallery`、`avatar`；
+- `tool_call`、`tool_result`、`agent_status`、`approval_request`、`artifact`、`citation`、`error`。
+
+用户输入可使用 Markdown 内嵌 Mermaid、代码和数学定界符；服务端必须使用确定性 parser 规范化为 canonical ContentBlock，记录 parser version，不把原始 HTML 当可信内容。
+
+### 5.2 流式事件
+
+统一事件：
+
+```text
+content.block.started
+content.block.delta
+content.block.progress
+content.block.completed
+content.block.failed
+content.block.cancelled
+message.completed
+```
+
+- Event 在 Run 内有单调 `sequence`；Block delta 有单调 `delta_index`。
+- 客户端按 event ID 和 `(block_id, delta_index)` 去重；缺口通过重放或最终 Message 对账，不猜顺序。
+- Completed Block/Message 是权威快照，临时累积状态必须可丢弃重建。
+- SSE 用于 Run/通知；WebSocket 用于实时语音、协同和设备双向会话。
+
+### 5.3 分级实时渲染
+
+- Markdown/text 增量显示并节流解析；未闭合结构保持源码态。
+- Code 按行/时间片高亮，不逐 token 执行 Shiki。
+- Math 仅在定界符闭合或 Block 完成后渲染；必须有源码/fallback text。
+- Mermaid 仅在 Block 完成后以 strict mode 隔离渲染；失败显示源码和错误摘要。
+- 图片、视频、音频和文件先显示结构化进度，资源 ready 后加载。
+- Tool/Agent/Approval 使用状态替换，不拼接自由文本模拟状态。
+
+### 5.4 前端安全与可访问性
+
+- 禁用 Markdown 原始 HTML；URL/协议/目标域校验；外链 `noopener noreferrer`。
+- Mermaid 禁止 click、HTML label、外部脚本和危险初始化；SVG 二次净化。
+- KaTeX/MathJax 禁止 trust/宏注入并限制展开；Shiki 只高亮不执行。
+- 图片必须有 alt；音视频有字幕/转写；公式有 MathML/fallback；图表有标题、说明和源码替代。
+- 流增量不持续抢焦点；错误、审批和费用不能只靠颜色表达。
+
+## 6. 插件、Agent 与安全
+
+- 所有可扩展能力皆插件；认证、授权、数据隔离、审批、交易 Ledger、审计和 Sandbox 内核不可插件化。
+- 只有 bundled Core plugin 可进主进程；声明式/远程插件默认受限；可信本地代码插件也进入独立进程或容器。
+- Python import、Node `vm` 和 WebView 不是安全隔离。
+- 插件 Manifest 声明版本、依赖、数据、网络、设备、费用、外部目的地与现实后果和配置 Schema；升级新增权限必须重新确认。
+- Run 固定 PluginSnapshot；活动 Run 不热替换。安全撤架可以阻断新调用，但保留历史审计。
+- 子 Agent 的工具、数据、网络、预算和权限是父 Run 的交集子集；不继承审批令牌，默认不能写长期记忆。
+- Tool input 是不可信模型输出，必须 Schema 校验、Policy、审批、路径/URL 约束、资源限制和幂等。
+- 无符合策略的 Sandbox 时拒绝执行，不静默退化到宿主。
+
+## 7. 社区、协作、设备与交易
+
+- PersonalDomain、Workspace、Community、Marketplace、Finance 和 Diagnostics 使用不同授权策略。
+- 社区私信采用服务端治理的一对一/小群聊，不宣传 E2EE；支持举报、屏蔽、审核和多端同步。
+- 公开角色 Release 不包含私密记忆、关系、对话、设备授权或密钥。
+- Tauri v2 Desktop/iOS/Android 的文件、相机、麦克风、屏幕、位置和通知同时受 OS 权限与 `device_grant` 约束；采集有持续指示并可即时撤回。
+- 购买不等于安装插件，安装不等于启用，启用不等于授予新增权限。
+- 支付 Webhook 验签、按事件 ID 幂等、允许乱序；客户端金额不可信；退款、分成和结算可对账。
+
+## 8. 语言与框架规范
+
+### 8.1 TypeScript / Next.js
+
+- TypeScript 开启 `strict`；禁止无理由 `any`、非空断言和重复定义 API 类型。
+- 使用生成的 OpenAPI 类型；表单边界使用 Zod/React Hook Form；服务端状态使用 TanStack Query。
+- React Server Component 默认；只有需要浏览器 API、交互状态或第三方客户端库时使用 `"use client"`。
+- 不在 render 中产生副作用；Effect 必须清理订阅、Timer、Worker 和 WebSocket。
+- ContentBlock renderer 采用穷尽判别联合；未知类型走兼容占位，不能崩溃。
+- 长列表使用虚拟滚动；Markdown/Math/Mermaid/Shiki 高成本处理放 Worker 并按 content hash 缓存。
+- 图标统一 Lucide；界面禁止表情符号代替图标、状态或操作。
+- 测试：Vitest + Testing Library；核心旅程和跨端行为使用 Playwright。
+
+### 8.2 Python / FastAPI
+
+- Python 3.12+，使用 uv；格式/Lint 用 Ruff，类型检查用 mypy，测试用 pytest/pytest-asyncio。
+- FastAPI 边界使用 Pydantic v2；领域对象不依赖 HTTP Request/Response 或 Provider SDK 类型。
+- SQLAlchemy 2.0 typed mapping；迁移只用 Alembic；禁止运行时隐式建表修改生产 Schema。
+- I/O 使用 async；不得在事件循环执行阻塞模型、文件、媒体或数据库操作。
+- Provider、Tool、Storage、Payment 通过明确 Port；异常映射为稳定领域错误，不匹配错误字符串。
+- Decimal/整数处理金额；时间统一 aware UTC datetime。
+- 模型/工具流必须可取消，资源使用 `async with`/`try-finally` 释放。
+
+### 8.3 Rust / Tauri
+
+- 使用 Tauri v2 和 stable Rust；`cargo fmt`、`cargo clippy -- -D warnings`、`cargo test`。
+- Tauri command 输入使用 serde/specta 类型并校验；不暴露通用 Shell 或任意路径命令。
+- Capability/permission 最小化，桌面与移动平台分别声明；敏感命令验证用户、设备和 DeviceGrant。
+- 路径 canonicalize 后限制在授权根目录；秘密使用系统 Keychain/Keystore，不写普通配置或日志。
+- `unsafe` 仅在无安全替代时使用，封装最小并写明不变量和测试。
+- Tokio 任务支持取消和超时；不要持锁跨 `await`。
+- 共享 TypeScript 类型由 specta/OpenAPI 生成，不手工漂移。
+
+### 8.4 C++（灵台引擎）
+
+- C++23 与 CMake；`clang-format`、`clang-tidy`，编译警告全开并视为错误；测试与 fuzz 框架在建立工程时按 ADR 登记。
+- 对外只导出 `extern "C"` 的 `hj_*` 符号与不透明句柄；异常、STL 类型、RTTI 和 C++ 类不得跨越 ABI 边界；入口函数捕获一切异常并转换为 `HjStatus`。
+- 同一核心支持进程内嵌入与 gRPC 独立服务（`hunjing-lingtai-server`）双形态；任何能力在两种形态语义必须一致，服务仅限部署内网并经 mTLS 认证。
+- 内存全部 RAII，禁止裸 `new`/`delete`；引擎分配的缓冲只经 `hj_buffer_free` 释放；字符串一律 UTF-8。
+- `HjEngine` 线程安全，会话句柄单线程亲和；回调在调用线程同步执行且回调内禁止再入引擎；不持锁跨回调。
+- 全部引擎输入（Markdown、模型输出、工具参数、查询、Webhook 字节）按不可信输入处理，长度/深度/节点数有硬上限；`hj_transform` 与 `hj_policy` 为 fuzz 必测目标。
+- 每次提交跑 ASan/UBSan，线程路径跑 TSan，并维护 ABI 快照与双形态 golden 一致性测试。
+- 引擎无权威状态、不做网络/文件/数据库 I/O（显式只读索引除外）；引擎缺失或服务不可达时宿主 fail closed，禁止宿主内第二实现降级。
+- 第三方库进入前按官方文档、许可与维护状态评估，gRPC/ANN/分词等选型以补充 ADR 登记。
+
+### 8.5 Go（仅在 ADR 决定拆出高并发服务时）
+
+- 版本以 `go.mod` 为准；`gofmt`/`gofumpt`、`go vet`、`golangci-lint`、`go test ./...`。
+- 所有外部 I/O 接受 `context.Context`，传播取消和 deadline；不把 Context 存入 struct。
+- 错误使用 `%w` 包装并以 `errors.Is/As` 分类；不匹配错误字符串。
+- Goroutine 必须有 owner、退出路径和测试；channel 由发送方关闭；禁止无界队列。
+- HTTP/Header/流式协议由共享契约生成或验证，不单独发明模型协议。
+
+### 8.6 SQL 与存储
+
+- 表/列/index 使用 `snake_case`；外键、唯一约束、检查约束和租户条件在数据库层落实。
+- 所有 Query 明确 PersonalDomain/Workspace/Finance scope；禁止先全表读后应用层过滤。
+- N+1、无界列表和 `%keyword%` 全表扫描必须在实现前处理或有量化例外。
+- 向量、图、搜索和缓存只保存可重建投影，删除和权限变化必须传播。
+
+## 9. 复杂度与变更规范
+
+- 只改目标所需文件；匹配既有命名、注释密度和风格；保护用户已有改动。
+- 删除自己引入的无用代码、导入、配置和孤儿注释。
+- 函数有效逻辑超过 40 行、圈复杂度 >10、认知复杂度 >15、参数 >5 时应拆；确需保留须说明原因和风险。
+- 不为一个实现创建接口/工厂/配置层；但稳定跨模块/插件/Provider 边界需要 Port 时不受此限制。
+- 不重写或删除已有注释，除非需求明确要求或注释已失真。
+
+## 10. 验证纪律
+
+- 中大型或安全/状态/边界/并发/外部依赖变更先写失败测试，再实现通过。
+- 逻辑变更优先覆盖公共行为；核心逻辑自动化覆盖目标 80%+。
+- 每条需求交付前核对：需求 → 实现位置 → 调用点 → 测试 → 运行证据。
+- 新函数、类、配置、事件和 ContentBlock 类型必须有真实调用/消费点。
+- 新依赖、资源、Header、事件、ID 和配置名称必须验证真实存在且与契约一致。
+- 纯文档变更可不跑代码测试，但必须验证内部链接、Mermaid、Markdown 和契约引用。
+- 不报告虚假完成；测试失败、步骤跳过和未实现项必须明确说明。
+
+## 11. 文档与图表
+
+- 正式文档统一在 `docs/`；新增入口同步 `docs/README.md`。
+- 稳定 API/字段/ID/事件/错误只在 `docs/contracts/` 和生成 Schema 定义；下游引用，不复制可漂移值集。
+- 架构、流程、时序、状态和 ER 图统一使用 Mermaid，提交前必须实际渲染验证。
+- 产品文化名更新 `docs/product/cultural-language.md`；工程值更新契约；两层保持一对一映射。
+- 每次功能/API/状态变化同步相关产品、架构、契约、TODO 和测试文档。
+
+## 12. 目录与配置
+
+- `docs/`：文档；`logs/`：本地日志；`db/`：本地数据库；`config/`：应用配置；`docker/`：Docker 文件。
+- `.env.example` 位于根目录，列出环境变量和中文说明；只提交 `.env.example` 和其他不含秘密的 `*.example.*` 配置，不提交真实 `.env`、密钥、数据库、日志和用户数据。
+- 代码导入使用语言包/alias 的项目根路径；运行时文件路径通过统一项目根解析器或配置解析，不依赖进程当前目录。
+- Docker 容器名以 `hunjing-` 开头；Compose 不使用顶部 `version`；本地默认 SQLite，正式环境按完整 1.0 能力启用 PostgreSQL、Redis、对象存储和 Worker。
+- 本地启动、测试、迁移、生成和检查统一通过根 `Makefile`；新增命令同步 `make help`。
+
+## 13. Git 与交付
+
+- 不覆盖、重置或删除用户未授权的现有改动。
+- 不执行 `git reset --hard`、强制推送、清理未跟踪文件等破坏性操作，除非用户明确要求并确认目标。
+- 只有用户要求时提交或推送；Commit 使用简体中文的 Conventional Commits/Gitmoji 规范。
+- 提交前运行适用的 format、lint、typecheck、test、OpenAPI drift、Markdown/Mermaid 和安全检查。