forked from bai/curriculum-project-hub
ChickenPige0n
854c6189bb
Add a shared transparent OrganizationAgentConfigFolder tree for grouping agent roles and skills in the admin UI without affecting identity, bindings, run loading, or slash commands.
60 lines
4.9 KiB
Markdown
60 lines
4.9 KiB
Markdown
# AGENTS.md —— agent 操作手册(全 repo)
|
||
|
||
本 repo 是 monorepo。先读根 `README.md` 的"宪法"5 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。
|
||
|
||
## 这个 repo 是什么
|
||
|
||
- `spec/` 是一份**人机共识的契约**(Lean 语义母本),是产品语义的上游参照。
|
||
- 其余部件(将来的 `spec/` 外文件夹)是**向 `spec/` 对齐的实现**。
|
||
- `hub/` 的平台层按 SaaS 形态演进:`Organization` 是 tenant root;`Project`/`Team`
|
||
必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020 / `Spec.System.Organization`)。
|
||
- org 后台 project explorer 里 `Folder` 是透明组织节点,不是权限资源;project 仍是权限边界。
|
||
普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021 /
|
||
`Spec.System.ProjectWorkspace`)。
|
||
- 每个 org 自选 BYOK 或平台托管 model provider connection;平台托管也必须是该 org
|
||
独享的 key/base URL,不得让无关 org 共用 process-global provider key(见 ADR-0021 /
|
||
`Spec.System.Organization`)。
|
||
- Feishu/provider secret 使用本地版本化 master-key keyring 的信封加密;生产由 systemd
|
||
credential 注入,运行时只允许显式 org/project scope 的 fail-closed resolver,不得回退
|
||
process-global credential;Agent child 只接收 run-scoped loopback proxy capability,
|
||
不接收 org provider credential(见 ADR-0024 / `Spec.System.Organization`)。
|
||
- 生产容量按不可突破的 platform ceiling 与 org 可下调 policy 分层;有效限制取两者较低值。
|
||
Agent admission 必须持久、有界、跨 org 公平且显式背压(见 ADR-0022 /
|
||
`Spec.System.Capacity`)。
|
||
- 平台管理员只通过独立的 platform-owned 飞书应用与可撤销 Platform Session 认证,不复用
|
||
客户 `User`/org membership;平台写操作与 append-only audit 同事务,break-glass 只走
|
||
双因子的离线恢复流程(见 ADR-0023 / `Spec.System.PlatformAdministration`)。
|
||
- 受控 alpha 暂采用一 Organization 一具名 systemd Silo:独立 database role/database、
|
||
service identity、workspace、keyring 与 Feishu/provider connection；进程必须由
|
||
`HUB_SILO_ORGANIZATION_ID` fail-closed 绑定唯一 org，平台后台不开放。共享 SaaS
|
||
控制面与 Docker adapter 后置(见 ADR-0025)。
|
||
- Agent role 与 skill 是 Organization-scoped 动态运行配置：role 组合 model、system prompt、
|
||
tools 与已安装 skill；skill 版本进入 content-addressed 持久存储，run 只读加载所选快照。
|
||
每个 Organization 必须且只能有一个启用中的默认 role；新建群绑定从该默认值初始化，之后
|
||
`ProjectGroupBinding` 持久化群内当前 role，run 在接纳时冻结该 role。飞书公开 slash 协议只含
|
||
`/project`、`/usage`、`/help`；role、会话、目录操作走 `/project` 卡片，Claude 原生
|
||
`/compact` 只能由卡片动作以未经包装的精确 prompt 转发。
|
||
`settingSources: []` 继续禁用项目/用户配置加载，不得把任意 workspace `.claude` 配置变成
|
||
运行时能力(见 ADR-0018)。
|
||
skill/role 的管理面分组由一棵 org 内共用、可嵌套的 folder 树承载：透明组织节点，
|
||
不进入身份、解析与授权——name/roleId 仍 org 内唯一，role→skill 绑定、run 加载与
|
||
slash 命令均不引用 folder;folder 归属变更是 label 类变更,不归档会话;仅空 folder
|
||
可删(见 ADR-0028 / `Spec.System.AgentRole`)。
|
||
- 项目发现由 `ProjectDiscovery` 模块统一承载：PostgreSQL `pg_trgm` 搜索派生文档、项目编号
|
||
归一化、完整 Folder breadcrumb、MANAGE 授权过滤与分页都在该模块内；飞书卡片只是 adapter。
|
||
`Project`/`Folder` 仍是事实来源，搜索文档必须可重建且由数据库触发器同步，禁止调用方双写。
|
||
系统 `Inbox` 只作为未分类项目的内部落点，不作为业务 folder 暴露；已绑定群通过
|
||
`@bot /project` 随时打开项目管理卡片，重命名仍走 org-scoped MANAGE 授权与审计。
|
||
|
||
## 纪律
|
||
|
||
1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。契约里 prose doc 注释是语义的唯一权威来源;契约没写的,就是没定的。
|
||
|
||
2. **凡契约未写明者,不得假设。** 遇到标了 `OPEN` 的地方,或契约根本没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。
|
||
|
||
3. **改 `spec/` 必须保持其 `lake build` 通过。** 在 `spec/` 目录下跑 `lake build`。新增声明必须带 `/-- … -/` doc 注释和恰当标签(`PINNED` / `OPEN` / `ADR-NNNN`)。规范见 `spec/README.md`。不准用 `sorry` 把 build 糊绿。
|
||
|
||
4. **实现向契约对齐;偏离必须 surface。** 没有 CI gate 替你把关 spec↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与契约不一致时,报告它,不要默默让其中一边将就另一边。
|
||
|
||
5. **写操作谨慎。** 线上操作、git 写操作前与开发者确认(这是开发者的全局偏好)。
|