git:20260924.789f9d4 to git:20260924.4350616

---

name: team-workspace

description: "Open and operate TeamDesk, a local AI team workspace built on existing Codex tasks. Use for 打开 AI 团队工作台、创建或绑定 AI 员工、检查团队 metadata、配置 TeamDesk 原生接入与自动工作记录。"

---

# TeamDesk 团队工作台

## 首次安装

首次安装使用仓库根目录 `install-teamdesk.sh`，一次检查依赖、通过原生 CLI 安装插件、生成并核验图标；详见 [插件安装说明](../../README.md#安装与启动)。从 clone 运行使用本地来源，下载独立脚本使用 GitHub main。缺失编译工具时按提示补装并重跑；不以克隆、缓存存在或创建图标代替完整安装验证。hook 信任仍由人类明确确认。

## 打开工作台

解析本文件目录，执行 scripts/launch.sh start，用 open_in_codex 打开输出的本机 URL。默认端口 4322。不能把工作台部署到公网，不复制完整对话或创建独立模型执行环境。

用户要求专用启动图标时，执行 scripts/launch.sh install-icon，生成用户 Applications 下的 TeamDesk.app 与桌面链接。通过原生应用工具打开该图标，可同时启动/复用工作台和共享 Codex Desktop，再明确用 Safari 打开；每次解析当前 Codex 与唯一的本机 TeamDesk 安装目录；无需先运行 Codex CLI 查询插件。已有普通模式 Codex 只提示正常退出，不强制关闭、不改全局启动项。构建要求 Xcode Command Line Tools；日常启动不依赖编译器。

首次启动为空团队。在员工页新建员工或绑定已有 Codex 任务。业务编号、名称、类别、阶段由指定负责人维护；验收由人类操作。

## 按需接入与入职

- 读 [连接说明](references/connection.md)。工作台直接连接**桌面实际使用的同一个 App Server**；启动前核对进程归属、桌面连接及服务进程 ID。仅共享本地历史不算连接成功。

- GUI 提交即派发，不创建或恢复模型 heartbeat。旧的 connection-next/register/ack CLI 已停用；迁移时旧待派请求保留待核对。

- 若桌面尚未使用共享连接，让用户正常退出 Codex，然后在「团队设置」点击「以共享接入启动 Codex」。不强行关闭其他正在工作的任务。不改全局启动配置；正常打开 Codex 可恢复默认连接。

- 插件自带 Stop hook。人类可在工作台审查配置和脚本，再明确点击信任；后端只向原生 config/batchWrite 提交显示过的当前定义摘要，并重新读取核验。不能由 agent 代替用户点击、写任意信任或默认批准新定义。同一已信任定义直接复用。

- 添加员工自动配置绑定并发起原生轮次检查。只有当前版本 hook 记录与对应原生完成事件一致，才标记记账就绪；不把配置或脚本单测冒充触发成功。

- 离线或缺少信任时保留输入。FIFO 进入原生队列；steer 校验当前轮次和业务关联。回执不确定时先核对，不盲目重复派发。

## 员工模型与运行偏好

员工详情可查看和设置模型、思考深度与速度。默认值以其关联 Codex 会话为准，新建或换绑继承原生配置；TeamDesk 只同步 metadata，不持续覆盖原生设置。只通过原生 thread/settings/update 修改这三个字段，保存须读回核验。修改影响后续轮次（含排队中），不切换当前执行轮次，不触发新业务、不修改工具或权限。断线显示最近同步值，未确认的写入先读回核对，禁止自动重试。新建任务的临时覆盖入口保留 Coming soon。

## 员工工作

收到业务或探测输入时，读 [员工协议](references/worker.md)。使用宿主 CODEX_THREAD_ID 和本次 requestId 读取 inbox；不伪造身份。按技能流程工作并通过原生 codex-app-tools 交接，遵守协议中的发送、接收、回传可见性要求。

原生结构化问题及时显示在决策箱，回答保留 questionItemId。原生审批只由真实人类选择并回传当前回调；私密输入和失效回调仍在 Codex 中处理。TeamDesk 不改变原生任务的权限。

## 部门与共享资料

员工所属部门、部门职责和联系人由工作台维护。每位员工最多属于一个部门，也可未分配；支持移出、转部门及部门删除/恢复，保留会话、任务和历史。使用 CLI `query me / departments / department / employee` 按需找人，同部门读取技能描述，跨部门读取岗位与部门职责。`query resources` 是团队/本部门的生效资料索引，`query resource ID` 读取指定版本；界面草案不作为员工规则。普通资料先编辑保存草案、确认发布后生效；删除停止员工查询，恢复先回到草案并需重新发布。系统内置协议在资料库中只读。每次 inbox 必须指定当前 requestId，不展开全员目录或全部历史任务。

验收通过和退回均发送原生通知。通过通知只确认收到并生成 acceptance_receipt，不改任务证据与验收版本，不自动启动后续工作。

## 运行与交付

新建独立任务（FIFO）也支持同一助手联动撰写任务目标与完成标准：参考所选负责人、协作者及相关生效资料，用户选择采用一个或两个字段，原“保存并交给 Codex”才派发。助手不改变负责人、协作选择或输入方式；steer 沿用原输入流程。工作约定／SOP 撰写近期暂缓。

三类 AI 撰写均可在要求中直接提及本地仓库名或路径；无需导入团队资料库。未读到指定资料时显示待完善，补路径/选择候选后重试，或由人类明确暂不参考。参考依据包含实际读取文件、行范围、时间和文件哈希。旧助手升级时保留历史及原生链接；不会改变员工任务的工具权限。

部门职责和员工工作说明表单可点击“AI 帮我写／完善”，用一句话说明意图，按需回答短问题，再预览建议、假设、冲突和修改对比。支持继续修改及历史查看；采用仅回填表单，仍需用户点击原保存按钮。助手复用现有共享 App Server 中的专用撰写任务，不占员工名额，不启动业务。其他长文本入口的评估见插件 docs/AI-WRITING.md。

launch.sh status 查看服务，stop 只停止工作台，员工继续由 Codex 管理。数据在用户 Application Support/TestAny/TeamDesk，测试可使用 TEAMDESK_HOME。不得在插件缓存写运行数据，私有证据不提交仓库。

交付须区分：本地保存、原生队列接受、员工实际收到、hook 实际触发、负责人报告完成、人类验收。诊断和 UAT 见插件 README 与 docs/UAT.md。