chenxin/hunjing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
28127949dbd977a4ef6cbc7281d824947103c90d
hunjing/docs
T
History
chenxin 3fbcd0437c 🎉 feat: 建立阶段 0 工程骨架与 OpenAPI 契约机器化（WP-01 起步） 
- Makefile：统一命令入口（backend/engine/docker/openapi/generate，含 make help）
- backend：FastAPI + uv 最小工程，统一错误体（契约第 7 节）、ADR-015 平台 ID 生成与校验（uuid-utils）；pytest 7 项、ruff、mypy strict、启动冒烟全部通过
- engine：灵台引擎 C++23/CMake 骨架，按 Lingtai C ABI 契约实现 lingtai.h（13 个 HjStatus、版本协商、句柄表防二次释放、线程局部错误上下文）；doctest 5 用例通过，nm 验证仅导出 hj_* 符号
- openapi：OpenAPI 3.1 单一真源初始版（错误体/分页/Money/首批平台 ID/ContentBlock 全 21 类型/流事件 envelope），Redocly lint 0 错误、bundle 通过
- frontend：Next.js 最小骨架，openapi-typescript 生成 API 类型并通过 strict tsc
- docker：hunjing-postgres（pgvector:17）compose；.env.example 与 config 示例
- ADR-025：登记测试与契约工具链（doctest/libFuzzer/Redocly/openapi-typescript/uuid-utils）
- desktop：Tauri v2 占位与初始化说明（WP-10 启动）
2026-09-09 21:45:04 +08:00
..
architecture
📝 docs: 统一 PostgreSQL 主库并固化索引命名约定
2026-09-09 21:14:10 +08:00
contracts
📝 docs: 建立魂镜完整 1.0 设计文档体系
2026-09-09 21:07:14 +08:00
decisions
🎉 feat: 建立阶段 0 工程骨架与 OpenAPI 契约机器化（WP-01 起步）
2026-09-09 21:45:04 +08:00
delivery
📝 docs: 统一 PostgreSQL 主库并固化索引命名约定
2026-09-09 21:14:10 +08:00
product
📝 docs: 建立魂镜完整 1.0 设计文档体系
2026-09-09 21:07:14 +08:00
research
📝 docs: 建立魂镜完整 1.0 设计文档体系
2026-09-09 21:07:14 +08:00
security
📝 docs: 建立魂镜完整 1.0 设计文档体系
2026-09-09 21:07:14 +08:00
README.md
📝 docs: 建立魂镜完整 1.0 设计文档体系
2026-09-09 21:07:14 +08:00

README.md

Hunjing 文档

文档状态：完整 1.0 目标设计。仓库尚无对应实现，所有 TODO 完成并通过发布门前不得表述为正式 1.0。

阅读顺序

  1. 产品定义与边界
  2. 产品宪章
  3. 完整 1.0 范围与发布门
  4. 指标与反指标
  5. 参考项目研究
  6. 灵台引擎研究
  7. 系统架构
  8. Agent 运行时
  9. 插件系统
  10. 灵台引擎架构
  11. 媒体与设备架构
  12. 社区、协作与市场架构
  13. 前端富内容实时渲染
  14. 数据架构
  15. 记忆与知识架构
  16. 中国古代神话与道家文化语言体系
  17. 协议与稳定标识
  18. API 总体约定
  19. Hunjing Native API
  20. 模型网关兼容 API
  21. 实时 API 与 Webhook
  22. 内部端口、事件与插件协议
  23. 统一富内容与流式协议
  24. Lingtai C ABI
  25. Lingtai Service
  26. 1.0 API 表面总表
  27. HTTP 与事件契约
  28. 运行观测契约
  29. 安全与诊断访问
  30. 架构决策
  31. 1.0 实施 TODO
  32. 设计阶段交接文档

文档分类

目录 职责 不承载
product/ 1.0 用户、范围、验收和 2.0 边界 代码结构和供应商细节
research/ 外部证据、采纳与拒绝理由 项目契约
architecture/ 组件、运行时、媒体、生态、数据与扩展边界 稳定枚举值
contracts/ ID、字段、请求头、事件和错误 产品愿景
security/ 信任边界、授权、交易、内容治理和诊断访问 普通功能说明
decisions/ 已作出的重大取舍及后果 教程
delivery/ 1.0 工作包 TODO、验收证据、统一发布门和阶段交接 2.0 实现计划

事实优先级

flowchart LR
  P[产品定义] --> D[架构决策]
  D --> C[契约]
  C --> I[实现]
  I --> T[测试与运行证据]

发生冲突时，上游定义约束下游；运行事实不能被文档否认。实现与文档不同时先记录偏差，再决定修正文档还是实现。

1.0 维护规则

  • 稳定 ID、枚举、事件名、请求头和错误码只在 contracts/ 定义。
  • 架构文档引用契约名，不复制完整值集。
  • 外部项目只提供证据和模式，不自动成为运行依赖。
  • Mermaid 使用短标签和标准图类型，不嵌入主题样式。
  • 新文档必须从本索引可达；删除文档必须同步入口。
  • Native Message、社区内容和 Agent 输出使用统一类型化 ContentBlock；Markdown 内嵌 Mermaid/数学/代码在服务端规范化，前端按分级实时策略安全渲染。
  • 产品界面采用完整双层文化体系；稳定工程契约保持中性英文值。
  • 文档 TODO 是 1.0 必做项；正式实现不得用 TODO、pass、省略或假数据占位。
  • 完整 3D 建模器、LLM 直接改模和物理设备控制属于已确认的 2.0 边界，其他已列能力不得静默移出 1.0。
Reference in new issue View Git Blame Copy Permalink