hunjing/AGENTS.md

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 关系数据是权威事实源（ADR-024，不设 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 流式事件

统一事件：

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；索引命名使用 pk_/uk_/idx_/fk_ 前缀加表名与字段；外键、唯一约束、检查约束和租户条件在数据库层落实。
• 所有 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；开发、测试与自托管统一 PostgreSQL（ADR-024），正式环境按完整 1.0 能力启用 Redis、对象存储和 Worker。
• 本地启动、测试、迁移、生成和检查统一通过根 Makefile；新增命令同步 make help。

13. Git 与交付

• 不覆盖、重置或删除用户未授权的现有改动。
• 不执行 git reset --hard、强制推送、清理未跟踪文件等破坏性操作，除非用户明确要求并确认目标。
• 只有用户要求时提交或推送；Commit 使用简体中文的 Conventional Commits/Gitmoji 规范。
• 提交前运行适用的 format、lint、typecheck、test、OpenAPI drift、Markdown/Mermaid 和安全检查。