Files

T

chenchenandClaude Opus 4.8 0fe1d20d67 feat(agent): unify agnet→agent and implement client/runtime unification spec v0.1 core

按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。

命名统一(强制,无兼容):
- 全仓 agnet/Agnet/AGNET → agent/Agent/AGENT:后端 Go(路由 /api/agent/*、env AGENT_*、
  结构体/函数、19 个文件改名)、前端(agent-console/agent-hub、/api/agent 调用、i18n)、
  DB(表 agent_*、列 agent_id)、compose/.env、文档、脚本。
- DB 加幂等迁移 renameAgnetTablesToAgent():启动时 rename 老 agnet_* 表/列,保住生产数据。

统一方案核心(10 项):
- callback 统一 /api/agent/callbacks/runtime-events(路由/广播URL/函数名)。
- artifact 兜底判定改用 Runtime 权威信号 metadata.synthesized(§7.2)+ 结构化 artifact_type。
- Manager→Runtime 路径对齐 /api/agent/sub-agile/deployments(§2.2),{deployment_id} 回退 swarm_id。
- 状态裁决 display_status:Manager 唯一裁判,completed 无有效产物→needs_codegen/
  completed_without_deliverable(§10.6),接入 detail/timeline/workflow。
- GET /api/heicode/capabilities 能力发现(§6)。
- 模型策略 per_role(role_models)+ 收集 allowed_model_ids(§9)。
- resource_binding_id→secret_ref 服务端解析,客户端不再 inline secret_ref(§17.6)。
- 客户端统一路由层 /api/heicode/sub-agile|swarm/*(task≡deployment,复用控制面)+ workflow 投影。
- 日志分层 user_logs/debug_logs(§13)。

验证:go build ./... + go test(controller/router/model/middleware)全绿;前端 tsc -b + rsbuild build 通过。
待部署:VM .env 的 AGNET_*→AGENT_*;启动迁移自动 rename 表;其他三仓库需同步切到 /api/agent。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-01 23:45:10 +08:00

5.1 KiB

Raw Permalink Blame History

AGENTS.md — Heicode 单仓导航（给 Codex / 助手）

本文是 仓库根级 的快速地图与协作约定。细分栈的规则请看各子目录自带文档（避免重复与漂移）。

仓库地图（explore 摘要）

路径	角色	栈 / 备注
`cc-haha/`	Heicode 客户端：CLI（Ink）+ 本地 HTTP/WS 服务 + Desktop（Tauri + React）	Bun + TypeScript；产品入口 `bin/heicode`
`heicode/`	Heicode Manager：网关 + 管理控制台	Go（Gin/GORM）+ `web/default` 前端（Bun/Rsbuild/React）
`website/`	产品介绍站点	Next.js；根 `docker-compose.yml` 提供 `heicode-www` :8888
`docs/`	愿景、里程碑（`docs/milestones/`）、Agent 集成（`docs/integration/`）	Markdown

根 package.json 仅少量 workspace 级依赖（如适配器用到的包）；主要开发依赖在 cc-haha/package.json。

权威子文档（改代码前先打开对应一篇）

客户端（cc-haha）：cc-haha/AGENTS.md — 目录结构、运行命令、测试、提交约定。
网关（heicode）：heicode/AGENTS.md — Go 分层、JSON/i18n/DB 规则等。
产品愿景与交付节奏：docs/vision-heicode-full-stack-agentic-dev.md、docs/milestones/README.md。

最小开发闭环

# 依赖（客户端主体）
cd cc-haha && bun install

# 终端 A：本地 API（桌面端依赖）
bun run src/server/index.ts

# 终端 B：桌面
cd desktop && bun run tauri dev

联调本机 Manager（heicode）时常见：

HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 bun run src/server/index.ts

更多变量见 cc-haha/src/server/config/providerPresets.ts 与 cc-haha/src/server/api/heicode-auth.ts（如 HEICODE_<PROVIDER>_OAUTH_*）。

Heicode ↔ Manager 关键触摸点（代码索引）

客户端登录 / Provider：cc-haha/src/server/api/heicode-auth.ts，路由前缀 /api/heicode-auth/*（由 cc-haha/src/server/router.ts 挂载）。
模型发现：cc-haha/src/server/services/providerService.ts、cc-haha/src/server/api/providers.ts。
Provider 预设：cc-haha/src/server/config/providerPresets.json + providerPresets.ts。
Manager 侧 Heicode OAuth：heicode/controller/heicode_oauth.go，路由 heicode/router/heicode-router.go（例如 /heicode/oauth/authorize、/heicode/oauth/session）。

协作约定（根级）

改哪一层跟哪篇文档：Go 行为以 heicode/AGENTS.md 为准；客户端 TS/React 以 cc-haha/AGENTS.md 为准。
小步提交：沿用历史风格（如 feat: / fix: / docs:）；PR 写清影响面与验证步骤。
集成与「SK」边界：平台契约见 docs/integration/agent-platform-api-design.md，里程碑见 docs/milestones/。
不要臆测计费：计费与订阅在平台侧，不在 Heicode 客户端内实现。

Docker / 站点

根目录 docker-compose.yml：构建 website/ 静态站点镜像（端口 8888）。
Manager 本地编排以 heicode/docker-compose.yml 及仓库内 override 为准（若存在）。
VM / 生产同步代码：优先在目标机上 git clone / git pull 与本仓库远程一致；不要用 scp 传整份源码或 compose（仅在仓库不可用或紧急热修时例外）。
VM 部署后清镜像：每次 docker compose ... up -d --build 后执行 sudo docker image prune -f，清掉重建产生的悬空层；定期可 sudo docker system prune -f（不删仍在使用的卷）。避免只叠新镜像、旧层占满磁盘。

当前线上入口（2026-04）

Heicode 官网（Azure Static Web Apps）：https://ashy-dune-0e22d7b00.7.azurestaticapps.net
Heicode Manager（生产）：https://code.xinghanlab.com/

官网中的主按钮（登录/开始使用/CTA）默认应跳转到 https://code.xinghanlab.com/，避免出现历史 IP 地址。

Manager 生产拓扑（Azure）

应用层：Azure VM 上运行 heicode（当前用 Docker 容器承载应用进程）。
数据库与缓存：使用 Azure 托管服务（不在 VM 上跑 PostgreSQL/Redis 容器）
- PostgreSQL: heicode.postgres.database.azure.com / DB heicode
- Redis: heicode.redis.cache.windows.net:6380（TLS）
容器落盘：VM 仅承载应用进程；容器内产生的文件（如 /data 上传与持久文件、/app/logs）通过 bind mount 写到 VM 本地磁盘，便于备份与重建容器后不丢。编排见 heicode/docker-compose.azure-vm.yml，目录由环境变量 HEICODE_DATA_ROOT 指定。
说明：不要在生产 VM 上再启本地 postgres/redis 容器并指向业务库，避免与托管实例混淆。
镜像清理：发版构建后删除悬空/旧镜像层（见上文「VM 部署后清镜像」），防止 OS 盘被 Docker 占满。

若本文件与子目录 AGENTS.md / AGENTS.md 冲突，以子目录为准并及时更新根文件摘要。

5.1 KiB Raw Permalink Blame History Unescape Escape