手册 / 约定与参考

约定与参考

v2.15.0

UX 视觉风格、实体 URL / channel 约定、org-scoped 编号、Worker Discovery、ID 格式 —— 开发与使用中需要了解的跨切约定汇总。

§ 1 UX 约定

Web Console 遵循 Swiss Minimalist Style（瑞士极简主义）设计体系，以功能性、高对比度与大量留白为核心特征。所有组件设计满足 WCAG AAA 无障碍标准。

Grid 布局

12 列 grid：屏幕宽度 ≥ 1024px 时启用 12 列网格布局；< 768px 时回退到单列。
主布局采用三栏式结构：侧边栏 + 主内容区 + 可选右侧面板。
概览 / Fleet 页面使用 Bento Box Grid 模式，将多个摘要 widget 以不同 span 排列在卡片网格中。

字体层级

类型层级通过 size + weight + spacing 区分，不依赖颜色来表达层级关系：

用途	字体	大小 (rem)	字重
页面标题 (h1)	Space Grotesk	1.5	700
页面副标题	Space Grotesk	1.25	600
区段标签	DM Sans	1.125	500
正文 / 表格	DM Sans	0.875	400
代码 / ID / 时间戳	JetBrains Mono	0.75 – 0.875	400

数据列（侧栏计数 badge、fleet 指标、时间戳等）使用 font-variant-numeric: tabular-nums 保证数字等宽对齐。

Dark Mode

默认 light mode，dark mode 通过 <html class="dark"> 切换。全部颜色以 CSS 自定义属性（semantic token）表达，dark mode 只需翻转一组变量值。Dark mode 使用降饱和色调（desaturated tonal variants），而非简单反色。

交互 / 反模式

hover 过渡 200–250ms；仅用锐利阴影做层叠感，无渐变。
所有交互元素最小触摸目标 44×44px；所有 interactive 元素保留可见 focus ring。
禁止：装饰渐变 / blur、emoji 作图标（使用 Heroicons）、hover-only affordance（移动端无 hover）、为美观移除 focus ring。

§ 2 实体 URL / Channel 约定

ownerRef 格式

每个 Conversation 通过 owner_ref 字段关联到其拥有者（owning object），格式为 URI 字符串：

Conversation kind	ownerRef 格式	说明
`task`	`pm://tasks/{task_id}`	Task 1:1 绑定
`issue`	`pm://issues/{issue_id}`	Issue 1:1 绑定
`plan`	`pm://plans/{plan_id}`	Plan 1:1 绑定
`channel`	`id://organizations/{org_id}`	Channel 归属 Org
`dm`	（空）	DM 无 ownerRef

跨 BC 弱引用：ownerRef 是 Conversation BC 对 ProjectManager / Identity BC 对象的软引用（soft constraint），不声明 FK。Channel 可额外携带一个 nullable project_ref 软标签，仅作分组用途，不代表归属关系。

Conversation Kind 一览（6 种）

kind	场景	创建时机
`channel`	用户建立的话题频道（业务一等公民）	用户主动创建；name 全局唯一
`dm`	用户与 supervisor / agent 的一对一私信	用户开 DM 或 supervisor 主动 push 时懒创建
`task`	Task 专属消息时间线	Task 创建时同事务建
`issue`	Issue 专属议事时间线	Issue 创建时同事务建
`adhoc`	短期一次性对话	系统触发，TTL 默认 24h
`notification`	系统通知 / 周期 review	Supervisor 发起，通常单向

URL Deeplink 格式

前端路由采用 org-scoped 路径，所有 org-scoped 资源都显式挂在 org slug 下：

/{org-slug}/tasks                      # 任务列表
/{org-slug}/tasks/{task-id}            # 任务详情
/{org-slug}/issues                     # 议题列表
/{org-slug}/issues/{issue-id}          # 议题详情
/{org-slug}/plans/{plan-id}            # Plan 详情
/organizations/{org-slug}/projects/... # 项目相关页面

无隐含状态原则：API 与前端路由中 org 上下文必须显式体现在路径中（/api/orgs/{slug}/...），不依赖 session / query 参数推断当前 org。

§ 3 T<n> / I<n> Org-scoped 引用

Task 和 Issue 在组织内拥有递增的 org-scoped 序号，用于人类友好引用：

实体	引用格式	示例
Task	`T<n>`	T1, T2, T84, T245
Issue	`I<n>`	I1, I2, I19, I456
Plan	`P<n>`	P1, P42

实现机制

每个 Task / Issue / Plan 创建时从 pm_org_sequence 表分配 org 内唯一递增序号（org_number 字段）。
API DTO 中以 org_ref 字段返回渲染好的引用字符串（如 "T84"、"I19"），由后端 orgRefToken(prefix, orgNumber) 函数生成。
当 org_number 为 0（历史数据未回填）时，DTO 省略 org_ref 字段，前端 graceful fallback 到 hash handle 显示。

与内部 ID 的关系

T<n> / I<n> 是用户面 / 业务面的引用，底层实体主键仍是 ULID。两者映射存储在 DB 中：

# 用户看到的（UI / API / 面包屑 / @mention）
T84 — org-scoped 人类友好引用

# 内部存储（DB 主键、跨 BC 引用、文件系统布局）
01JEXAMPLE0000000000000000 — ULID

判据：终端用户会看到它吗？会 → 用 T<n> / I<n>（org_ref）。只有运维读 ~/.agent-center 才看到 → ULID 亦可。

§ 4 Discovery

Worker 支持项目自动发现机制，通过 WorkerDiscovery 配置驱动：

配置结构

{
  "scan_paths":    ["/home/user/projects", "/opt/repos"],
  "exclude":       ["node_modules", ".git", "vendor"],
  "scan_interval": "1h"
}

字段	类型	说明
`scan_paths`	`string[]`	Worker 扫描的本地目录列表，寻找项目仓库
`exclude`	`string[]`	排除的目录名 / 模式
`scan_interval`	`string`	扫描周期，duration 格式（默认 `"1h"`）

Project Mapping 机制

Worker daemon 按 scan_interval 周期扫描 scan_paths 下的目录。
发现的项目仓库以 proposal 形式上报给 center（worker_project_proposal）。
center 侧 accept proposal 后建立 worker ↔ project mapping，用于后续 Task dispatch 时选择合适的 worker。
Concurrency 配置（WorkerConcurrency.per_agent_type，默认 2）控制单 worker 上同时执行的 agent 数量。

配置入口：通过 CLI agent-center worker config set 或 Web Console → Environment → Worker 详情页修改 discovery / concurrency 参数。

§ 5 ID 格式

ULID 主键

所有实体主键使用应用层生成的 ULID（Universally Unique Lexicographically Sortable Identifier），不使用数据库自增主键。ULID 兼具全局唯一性与按时间排序能力。

01JEXAMPLE0000000000000000
└──────────┘└────────────┘
  timestamp     random

ID 分层：业务面 vs 内部面

面	使用 ID	出现位置
业务 / 用户可见	member-id（`agent-<8hex>`，Phabricator 式 hash）	UI、REST API、`@mention` token、ref token
内部 / 运维	ULID	DB 主键列、worker 文件系统布局、跨 BC 引用

member-id ↔ ULID 的映射存储在 DB 中；UI / REST API / @mention / ref token 一律不暴露 ULID。

IdentityRef 值对象

身份引用（identity reference）采用 kind-prefixed 格式，必须携带类型前缀：

格式	说明	示例
`user:<id>`	人类用户	`user:hayang`
`agent:<id>`	Agent 实例	`agent:01JXYZ...`
`system`	系统自身	`system`

校验规则：IdentityRef 必须为 system 或以 user: / agent: 开头且非空。裸 ID（不带前缀）会被 Validate() 拒绝。每个产出 identity-ref 的 tool / DTO 必须输出完整可消费形态（含前缀），消费端不应自行拼接前缀。

实体 ID vs 身份 ID

两者的引用规则不同：

Identity ref（agent / user / system）→ 引用必带 kind: 前缀
Entity id（project / task / issue / channel）→ ID 裸用，不加前缀

← 返回手册首页