Add reusable multi-session skill and five-page project workbench

references/design-system.md

@@ -0,0 +1,31 @@
+# 固定设计系统
+
+`assets/dashboard/` 是本项目的实际前端模板，不是截图参考。基于 React、TypeScript、Vite、Tailwind 与官方 shadcn/ui 组件；上游来源、授权和版本以模板内说明和 lockfile 为准。
+
+## 页面与布局
+
+复用官方 sidebar block 的侧边导航、页头和内容容器，登录复用官方 login block 的表单与组件。维持五个独立路由：
+
+| 页面 | 主要问题 | 内容 |
+|---|---|---|
+| 总览 | 现在进展如何？ | 少量状态统计、当前阶段/阻塞、重要汇报与决策摘要 |
+| 任务 | 谁在做什么？ | 工作包、状态、阶段、ETA 范围/依据和更新时刻 |
+| 集群 | 资源和调度是否可用？ | 节点内存/负载、NFS、Slurm、LSF与故障/采集时间 |
+| 沟通 | 我如何询问进度和讨论方案？ | 默认专门会话、来源明确的历史、输入框与投递状态 |
+| 决策 | 哪些事项需要我决定？ | 方案、影响、依据、待定与已决定记录 |
+
+总览不重现所有详情；页面不把数据全部挤在一个长列。窄屏折叠导航，沟通输入和消息列表保持可操作。
+
+## 颜色和组件
+
+- 固定 zinc 中性基础与官方 blue 主色，使用模板 CSS 变量；状态色仅表达成功、注意、失败和未知。
+- 不为每个任务生成另一套色板，不用渐变、发光或装饰插画取代信息层级。不在组件内散布临时 hex 色值。
+- 复用 Sidebar、Card、Badge、Button、Input、Textarea、Table、Progress、ScrollArea 等现有组件。新增交互先找已安装组件；确需增加时使用官方 registry/CLI并保留授权。
+- 区分运行状态、任务阶段与验证结论。颜色配文字，未知不使用健康颜色；预计时间有范围和依据。
+- 不写模拟运行数值当作生产内容。空状态说明缺配置、待同步或没有数据，尽量就近给可执行入口。
+
+## AI 修改方式
+
+先定位已有页面和数据适配层，复用组件完成需求；只在设计系统确需变化时修改集中 token。业务数据来自当前 API，不能为了套模板保留示例收入、销售图、假用户或无效按钮。
+
+提交前运行锁定依赖构建，并验证五页切换、刷新/返回、沟通会话目标、登录退出、过期/离线状态和窄屏布局。截图和生产数据仅留在私有验收产物，不自动加入公开库。

references/operations.md

@@ -0,0 +1,65 @@
+# 运行接入
+
+## 配置与部署
+
+服务由 `python3 -m agent_control.server --config <私有JSON>` 启动。先构建 `assets/dashboard/`，生产静态根默认是其 `dist/`；`web_root` 可指向本轮明确的构建产物。
+
+`scripts/setup.py` 在指定的当前账号家目录内建立私有运行根、配置与随机令牌，支持可选的自有 systemd 用户服务。不使用 sudo，不修改其他服务、网络、认证或防火墙。令牌文件权限600，运行根700，SQLite位于本地盘；不放入NFS、仓库或前端代码。
+
+`examples/control.example.json` 展示配置字段。`bind` 必须明确为内网/回环IPv4，`allowed_hosts` 包含确实使用的域名与端口；`title` 为当前项目名称，`primary_session_id` 指定人类沟通会话。保留来源校验，不关闭TLS或主机身份验证来解决连接问题。
+
+HTTP服务适合受控局域网或受保护隧道。跨不可信网络使用经过授权的TLS反向代理；公开代码仓库不意味着允许公开运行端口。服务使用单一操作员令牌，不是多租户权限系统；`source`标签不能证明人类批准。
+
+## API与状态
+
+读写API使用 `Authorization: Bearer <令牌>`；写操作还需 `X-CSRF-Token: 1`。浏览器令牌只放内存，退出清理。静态资源不包含运行数据。
+
+| 接口 | 用途 |
+|---|---|
+| `GET /api/state` | 任务、会话连接、事件、指标缓存、默认会话与项目标题 |
+| `POST /api/sessions` | 注册真实会话映射；`id/wp/name/role/worktree/thread_id` |
+| `POST /api/session-requests` | 保存新会话请求，不声称已经创建 |
+| `POST /api/tasks`、`PATCH /api/tasks/<id>` | 任务状态、阶段、ETA范围/依据和待决策 |
+| `POST /api/messages` | `session_id/text/source/idempotency_key`，定向消息 |
+| `GET /api/messages?session_id=<id>` | 当前会话最近500条消息及投递状态 |
+| `POST /api/worker/claim` | 串行领取，返回有限租期及领取身份 |
+| `POST /api/worker/start`、`renew` | 记录可能产生副作用的执行开始与续租 |
+| `POST /api/worker/submission` | 在发送前登记完整输入哈希，随后持久保存真实排队回执与观察到的turn |
+| `POST /api/worker/complete`、`uncertain` | 幂等回执或结果未知；未知停止该会话自动领取 |
+| `POST /api/messages/reconcile` | 人工核查后显式重试/失败，须记录依据 |
+| `POST /api/mirror` | 绑定thread的可见历史导入、更新、关联原输入/最终回复 |
+| `POST /api/events` | 工作包汇报、方案、决策、队列回执等事件 |
+
+任务状态：`queued/running/blocked/waiting/completed/failed/cancelled`。阶段：`planning/implementation/validation/integration/done`。完成任务须为done阶段。ETA包含最小值、最大值和依据；没有可靠估计时为空。
+
+源代码与行为测试维护精确校验规则。接口没有任意命令执行能力，采集不在HTTP请求中同步运行。
+
+`GET /api/messages` 的原输入行包含submission元数据。镜像只有在完整实际输入的服务端哈希、目标thread及已知turn都与登记记录一致时才能关联原消息；旧版本已投递但没有submission的消息须人工核查，不能伪造回执或重发来补登记。活跃领取中的最终回复可返回deferred，镜像不推进该项checkpoint，后续重试关联。正常输入上限32000字符；完整镜像正文及回复上限262144字符，对应请求体上限4MiB，超出明确拒绝而不截断或自动重执行。
+
+## 当前会话与桥接
+
+加载skill时默认绑定当前真实会话；用户明确要求专门入口才另建，并将其设为默认。用宿主受支持工具确认真实ID，建立项目归属与看板映射。不要把内部执行器thread和桌面会话混为一谈。
+
+执行器使用既有模型登录。集群未认证时让本机运行worker和mirror，服务/指标留在集群；模型凭据不离开本机。远程API可用 `control.transport="ssh"`：配置入口账号、独立私钥、`remote_client` 与 `remote_config`。客户端使用严格主机校验，在服务端内存读取服务令牌；不把令牌或模型认证拷进前端。
+
+`desktop_queue`模式向原thread使用官方`codex queue`发送。保存外部回执、输入哈希和观察到的turn，精确匹配完整输入，不把用户正文引用的标记当作回执。队列回执与历史的clientId并无已验证的一对一保证，不能擅自假定相等。独立`exec resume`遇到桌面writer锁时不得抢占；可用性必须按本机版本验收。
+
+镜像通过官方App Server分页历史读取用户、助手可见正文和明确的跨会话汇报；排除推理与工具日志。保留外部thread/turn/item ID、来源和修订；checkpoint绑定服务端点、会话和协议版本，换目标须显式处理旧状态。网页输入与最终回复关联原队列消息，去重且能补回超时后的真实最终结果。
+
+已开始的执行失联后不自动重跑。重启发现inflight或待对账时，先查保存的回执、原会话、现有进程和产物；不能因一个本机进程结束就认为远端操作没发生。确认原操作已完成则收敛回执，只有明确核查和批准后才重试。
+
+对已accepted/unknown的旧投递，不在同一message下更换输入哈希重试。核查并结束旧投递后，确需再次执行时建立带新幂等键的新消息，保留旧记录与人工依据；不要通过清空数据库恢复执行。
+
+Windows下桌面队列命令受系统命令行长度限制；过长消息与上下文明确失败，不截断用户正文后静默提交。可缩小上下文或按用户意图拆成多条消息。
+
+## 指标与扩展
+
+默认配置仅本机只读指标。远程主机必须在本地可信配置中明确列出并加入白名单，使用获准入口与身份。NFS只读挂载统计，不递归扫描工程。调度器wrapper路径由站点配置，wrapper仅接收固定采集参数。
+
+LSF主机/队列RUN计数可能是槽位数，不能等同作业记录数量。Slurm与LSF分别显示节点状态、队列/作业汇总、错误和时间；缺命令、缺配置与无权限不补零。新指标实现受控采集器和解析回归，不能让网页提交shell文本。
+
+## 定期汇报与验收
+
+用户要求定期汇报时，使用宿主正式heartbeat/automation工具，默认每10分钟检查活跃任务并向当前映射会话汇报。记录真实任务ID、目标会话和周期；项目结束后停止该项目的周期汇报。单独的后台Python进程不会自动产生模型汇报，不要误称已设置定时任务。
+
+真实验收分别记录：认证和来源保护、消息隔离/幂等、租期/失联恢复、同一真实会话往返、原会话汇报镜像、五分页及返回刷新、窄屏、真实采集、局域网直连。模拟通过不能替代真实模型/集群测试。原业务项目仍执行其自己的测试和原生工具验收。