帮助中心

Web 工作台是人和其他执行者共用的主界面：空间决定归属，项目承载目标，任务记录交付，文档和知识提供上下文，Loop 负责执行，人工门禁决定下一步。

1. 用邮箱注册或登录，在顶部切换到你要工作的空间（公司空间或个人空间）。
2. 在「项目」里新建项目，写清目标、范围、负责人和里程碑，再按里程碑建任务。
3. 在任务里写明验收标准，然后选择 Loop 与执行端发起运行。
4. 到「Loop → 运行记录」看节点进度；有等待确认的节点时到「审批」处理。
5. 把测试结果、截图或文档作为验收证据提交，确认后再关闭任务。

先认识六个关键概念

左侧菜单各自负责什么

任务状态怎么流转

1. 待办
2. 进行中
3. 待确认 / 待验收
4. 已完成

运行成功不等于任务完成。Agent 或 Loop 的状态不会自动改任务状态，只有提交验收证据并确认后，任务才会关闭。

逐菜单说明

下面按左侧 11 个菜单逐个说明：每个菜单是做什么用的、里面有哪些功能、以及什么情况下不该用它。

首页

作用：打开工作台的第一屏，回答「我现在该做什么、什么在跑、哪里卡住了」。

• 当前焦点：置顶显示一张当前任务卡，含任务 ID、标题、说明、负责人、执行方式与验收证据数量，并提供 继续推进 / 转交 / 标记阻塞 三个动作。
• 我的队列：只列指派给我的任务，按 全部 / 待处理 / 运行 筛选；我创建但已指派给别人的任务不在这里。
• Loop 运行：只列我负责或我发起的 Loop，按 全部 / 运行中 / 等待中 / 失败 筛选，等待人工与最近失败的运行会单独可见。
• 项目与团队：项目进度与风险、团队负载和自动化状态，用于判断要不要给人或 Agent 加派工作。

不该用它的场景：首页只做「当前该做什么」的聚合，不替代任务列表的批量操作，也不替代报表的周期分析。

任务

作用：所有工作项（人做的、Agent 做的）都在这里统一管理，是交付的主列表。

• 保存视图：全部 / 分配给我 / 本周到期 / 待验收 / 已阻塞，点一下切换常用范围。
• 视图形态：列表、看板、日历三种，同一批任务换不同看法。
• 筛选：按负责人、状态、优先级、项目、标签、归档筛选；配合排序调整阅读顺序。
• 任务字段设置：控制列表显示哪些字段，不改动数据本身。
• 批量操作：勾选多条任务后统一改负责人、状态、优先级、项目或归档；用「取消选择」退出批量模式。
• 分页：超过一页时用上一页 / 下一页翻页，页脚会显示匹配结果数量。

任务详情（点开一条任务）：顶部固定六个可编辑字段 —— 任务状态、任务负责人、任务优先级、任务项目、任务截止时间、定时规则；下面四个页签分工如下：

不该用它的场景：任务不是排期工具，里程碑和阶段属于项目；验收证据不足时不要直接改状态为已完成。

提醒

作用：集中处理「与我有关的变化」，避免在任务、项目、文档之间来回找。

• 范围筛选：全部 / 未读 / @我 / 系统。
• 单条处理：标为已读、标为未读、归档。
• 批量处理：进入批量模式后可多选，再执行「全部标为已读」或归档；「取消选择」退出。
• 跳转：每条动态都带任务 / 项目 / 文档 / 团队的入口，点进去就是对应上下文。

不该用它的场景：提醒只汇总通知，不保存业务状态；把提醒归档不等于任务完成。

Loop

作用：把业务流程（SOP）定义成可发布、可运行、可回放的线路，并在这里管理版本与运行结果。

定义与发布页签：

• 列表与指标：Loop 定义数、待发布草稿、已绑定项目、累计运行。
• 范围筛选：全部 / 任务 Loop / 项目 Loop；任务级是任务子流程，项目级可绑定项目或里程碑。
• 新建 Loop：从空白或模板创建，进入编辑器配置名称、用途、级别、负责人、状态、触发方式与草稿改动说明。
• 节点编辑器：节点顺序即执行顺序，可调整顺序与删除；节点类型有 Agent 节点、SubLoop 调用、人工门禁、工具节点四种；添加节点后为该节点选择模型与推理强度。
• 版本：草稿版本与最新发布版本分开显示；发布时必须填写改动说明，历史版本保留。
• 项目绑定：把 Loop 绑定到项目或里程碑，绑定 ID 用于追溯。
• 运行表现：成功率与累计运行次数，用来判断这条线路是否稳定。
• 运行图：把节点与连线画出来，包含返工 / 驳回回路；每种节点类型有图例说明。
• 详情动作：编辑、试运行、发布草稿版本。

运行记录页签：

• 指标：运行记录数、成功率、等待确认、平均耗时。
• 状态筛选：全部 / 运行中 / 成功 / 失败 / 等待确认。
• 记录内容：Run ID、Loop 版本、所属任务、触发方式、执行目标与设备、状态与耗时、开始时间。
• 运行详情：运行日志与输入快照可查看，用于复盘当时的输入与输出。
• 导出：按筛选导出记录、导出 CSV、导出运行快照，用于归档或离线分析。

不该用它的场景：已发布的版本不可改写，需要调整就发布新版本；Loop 不替你做业务决策，需要取舍的节点要显式加人工门禁。

Agent

作用：管理「谁来执行」——执行配置、正在跑的会话、以及需要人点头的审批。

• 执行配置：Agent Profile 列表（模型、工具范围、启用状态）与 Workers 表（Worker 名称、运行时、版本、容量、状态）；下方是 Linux Worker Pool 的实例情况。
• 在线会话：左侧是进行中的会话，右侧是会话详情 —— 执行上下文、会话事件、终端输出；会话动作有释放控制、重新连接、关闭会话；顶部状态条显示 Relay、执行端、控制权、journal 与序号。
• 新建会话：选择空间、项目、任务、执行目标（Kubernetes Worker / 本地 Agent / Docker Worker）、在线 Agent 设备、Worker Pool、模型站点、模型与推理强度。
• 审批：待处理数量在页签上显示；每条审批给出影响范围、策略、发起方与等待时长，动作有批准、退回修改、驳回。

不该用它的场景：审批不是「确认一下」的橡皮图章，批准前先看清影响范围与策略；关闭会话不等于任务结束。

项目

作用：承载目标与阶段，是任务、文档、知识和执行配置的归属。

• 列表与筛选：全部 / 健康 / 风险，行内显示进度、任务数、阻塞数、文档数、成员数、截止时间。
• 项目详情：里程碑列表（阶段、负责人、截止、状态）、里程碑下的任务、项目风险与逾期项。
• 项目设置：环境变量、仓库与分支、Worker 池、Loop 绑定、成员与角色、定时任务、项目知识。

不该用它的场景：项目不是任务看板，日常推进去任务里做；归档项目前先确认没有运行中的 Loop 与定时任务。

团队

作用：看「谁在忙、谁空着、工作怎么交接」，用于调度而不是考核。

• 范围筛选：全部 / 处理中 / 空闲。
• 成员线程：每个人的角色、当前队列数量与正在做的任务。
• 转交：把队列里的工作直接转给别人，交接记录留在线程上。
• 队列与交接：最近交接、阻塞与中断。

不该用它的场景：团队页反映的是当前负载快照，不做工时统计与绩效计算。

文档

作用：项目上下文的载体，也是 Agent 与 Loop 读取的知识来源。

• 范围与目录：按项目筛选（全部项目 / 具体项目），左侧目录树含需求文档、设计附件、帮助中心与回收站。
• 新建：新建文档、新建目录。
• 编辑与预览：编辑 Markdown，切换解析预览，或直接下载原文。
• 修订记录：查看历史版本与改动时间，可「收起修订记录」或「隐藏修订」专注正文。
• 正文结构：目标、交付状态、流程、附件等章节由文档自身组织，附件随正文展示。

不该用它的场景：文档继承项目权限，不要把密码、Token、连接串写进正文；未审核的内容不会成为权威知识。

报表

作用：按周期回看交付节奏与问题来源，用来调整流程而不是展示成绩。

• 时间范围：30 天 / 90 天 / 本季度，切换后所有指标同步刷新。
• 交付吞吐：完成量随时间的变化与完成率。
• Loop 结果分布：成功、等待审批、失败，以及中位耗时、重试后恢复。
• 主要失败原因：按分类汇总失败来源，指向要修的环节。
• 项目进度对比：多个项目的进度并排比较。
• 行动建议：结合指标给出现阶段值得处理的几件事。

不该用它的场景：报表基于已完成记录，需要实时状态请回任务或运行记录页。

扩展

作用：按当前空间选择公司，统一管理插件安装、插件市场与公司 Automation。

• 空间选择：用顶部空间选择器切换公司；个人空间或“全部”不承载公司插件与 Automation。
• 已安装插件：搜索、安装、升级、回滚、启用/禁用与卸载，所有操作写入审计。
• 插件市场：区分本地已安装与在线可获取，展示许可证、发布者、可信状态与撤销提示。
• Automation：公司范围定时执行、项目绑定与 Occurrence/Job 历史，与开发 Task 分开。

不该用它的场景：插件市场不是必选项；市场不可用时仍可从本地导入插件并继续核心工作流。

模板

作用：把跑通的流程与任务结构存下来复用，减少每次从零配置。

• 来源：Loop 市场（平台或空间发布）与我的模版。
• 排序：最新发布、星标最多、名称排序。
• 视图：卡片视图与列表视图切换。
• 动作：查看模板详情、加星标或取消星标。

不该用它的场景：模板是起点不是最终版本，套用后仍要按项目调整节点与验收标准。

设置

作用：维护账号、执行端与平台级配置。八个分节的作用见下方「在设置里能找到什么」与对应的第 02、05、06 部分。

• 个人资料：头像、姓名、账号状态与最近活跃时间。
• 安全：修改密码；查看登录设备并让其他设备立即退出。
• Agent 设备：授权 / 撤销设备、生成登录式绑定码（10 分钟有效）、轮换 Agent Token（明文只显示一次）。
• MCP 凭据：创建与撤销个人凭据，完整 Token 只显示一次。
• 公司管理：公司目录、成员与角色；owner/admin 在“执行网关”中管理 Worker 和运行镜像。
• 平台设置（仅站点管理员）：站点域名、文件存储与执行网关使用的 Worker 镜像目录。

不该用它的场景：设置只维护配置和凭据，不承载交付状态；改完权限或凭据后要回到任务、项目或运行记录里验证实际效果。

会话

作用：在浏览器里查看并接管正在执行的 Agent / Worker 会话，确认谁在控制、执行端是否在线。

• 执行上下文：空间、项目、任务、执行目标与策略，进入会话前先确认作用范围。
• 执行目标：Agent 或 Worker、设备与 Worker Pool、模型站点、模型与推理强度。
• 进行中会话：按在线 / 接入中 / 历史区分状态，切换会话查看对应终端。
• 终端与事件：输入直接进入 PTY，同时可查看会话事件、Relay 与 journal 状态。
• 连接控制：释放控制、重新连接、关闭会话；控制权可以随时收回。
• 隐私边界：平台只代理活动会话的终端字节、控制权和在线状态，不保存会话正文。

不该用它的场景：会话是执行通道，不替代任务状态；关闭会话不等于任务完成，交付结论仍以任务验收为准。

运行

作用：集中查看 Loop 的运行结果与节点进度，用来判断哪条线路稳定、哪里正在等待确认。

• 指标：运行记录数、成功率、等待确认、平均耗时。
• 状态筛选：全部 / 运行中 / 成功 / 失败 / 等待确认。
• 记录内容：Run ID、Loop 版本、所属任务、触发方式、执行目标与设备、状态与耗时、开始时间。
• 运行详情：运行日志与输入快照可查看，用于复盘当时的输入与输出。
• 导出：按筛选导出记录、导出 CSV、导出运行快照，用于归档或离线分析。

不该用它的场景：运行成功不等于任务完成；需要人工取舍时在审批处理，验收证据不足时不要直接关闭任务。

不走菜单的全局功能

• 空间切换：顶部左侧切换公司空间与个人空间；切换后所有菜单的数据范围随之变化。
• 全局搜索：顶部搜索框按任务、项目、文档搜索。
• 快速创建：顶部加号直接新建常用对象。
• 通知：右上角铃铛显示未读数量，点开是通知弹窗。
• 账号菜单：显示当前账号与角色，进入设置或退出。
• 帮助中心：本页；工作台内也有入口。

在设置里能找到什么

• 个人资料：头像、姓名、账号状态与最近活跃时间。
• 安全：修改密码；查看登录设备并让其他设备立即退出。
• Agent 设备：授权/撤销设备、生成登录式绑定码（10 分钟有效）、轮换 Agent Token（明文只显示一次）。
• MCP 凭据：创建与撤销个人凭据，见第 02 部分。
• 公司管理：公司目录、成员与角色；owner/admin 在“执行网关”中管理 Worker 和运行镜像。
• 平台设置（仅站点管理员）：站点域名、文件存储、执行网关使用的 Worker 镜像目录。

对应界面：工作台首页、任务、Loop 与运行记录、文档、报表、模板、设置

通过 MCP（Model Context Protocol），外部 AI 客户端可以查看空间和项目，并在同一权限边界内处理任务、文档和知识。所有调用复用平台的权限与审计规则。

1. 进入「设置 → MCP 凭据」，填写名称后点「生成凭据」。
2. 完整 Token 只显示一次，立即复制到受信任的客户端并保存在客户端的密钥存储或环境变量中。
3. 按下方 Codex 命令或其他客户端的 Streamable HTTP 字段完成配置；Token 不要写入配置文件。
4. 重启客户端会话，让客户端重新发现 humanthread Server 和工具列表。
5. 先调用 list_spaces 和 list_projects 确认权限范围正确，再执行写操作。
6. 不再需要时回到凭据列表点「撤销」，已发出的 Token 立即失效。

客户端配置片段

# Codex：先在客户端环境中设置 HUMANTHREAD_MCP_TOKEN，再执行
export HUMANTHREAD_MCP_TOKEN='<从设置页复制的 Token>'
codex mcp add humanthread \
  --url https://www.humanthread.cn/api/mcp \
  --bearer-token-env-var HUMANTHREAD_MCP_TOKEN

# 其他支持 Streamable HTTP 的客户端使用以下字段
server name: humanthread
MCP URL: https://www.humanthread.cn/api/mcp
HTTP header: Authorization: Bearer <Token>
protocol request: POST JSON-RPC (stateless)
private deployment: replace the URL with the address shown in Settings -> MCP Credentials

可用工具分组

任务 Loop 启动：start_task_loop 需要 commandId、taskId 和明确的 Local Agent 或 Linux Worker Pool。新命令会先取消同任务的活动 Loop 并使旧 Agent 租约失效；同一 commandId 重放返回原 Run，不重复启动。

补充边界：assign_task_branch 仅在开发模式部署中可用；get_project_environment_secrets 只按白名单返回加密信封，不是普通用户的明文环境变量查看入口。

必须回到 Web 工作台

MCP 当前覆盖单对象任务、文档、项目路线图、知识检索和活跃人工交互，不覆盖完整项目控制面。以下任务必须回到 Web 工作台完成。

当 AI 客户端找不到对应工具时，应引导用户明确回到上述 Web 入口，不要尝试用名字相近的工具替代。

权限与审计

• 凭据属于个人账号，只能触及你有权访问的空间与项目，不会因为客户端不同而放大权限。
• 创建项目、创建任务和创建文档通常不需要 expectedVersion；部分创建命令要求调用方提供 commandId。
• 更新项目路线图、项目状态或项目简称时，使用项目最新 version 作为 expectedVersion。
• 更新任务字段、排期、负责人、参与人、阻塞、状态、验收证据或派发 Agent 时，使用任务最新 version 作为 expectedVersion。
• 更新或追加文档时使用文档最新 version；移动或重命名文档不使用 expectedVersion，也不会创建新修订。
• 准备和提交知识批次使用 jobId、templateDigest、submissionId 等业务键，不依赖任务或文档版本号。
• 撤销凭据后所有调用立即失败；凭据列表保留创建时间与最近使用时间。

MCP 凭据是账号级密钥：不要写进文档、提示词、截图或提交到仓库。客户端只应读取当前项目所需的数据，批量导出前先确认项目权限边界。

对应界面：设置 → MCP 凭据

ht 是项目仓库里的命令行工具：登录平台、把发布的 Loop 结构物化到本地、检查本地配置是否可运行、修复或迁移结构，以及在没有桌面客户端时直接启动 Linux Worker。

1. 在项目仓库根目录登录：ht login --email <email>。
2. 首次初始化：ht init --project <projectId>，生成 .humanthread/ 结构。
3. 每次改动后自检：ht doctor，确认可达阶段都处于可运行状态。
4. 文件缺失用 ht repair --stage 重建，旧结构用 ht migrate --stage 升级。
5. 需要在服务器上执行时用 ht worker run，配置见第 06 部分。

命令参考

常用调用顺序

ht login --email you@example.com --password-stdin
ht init --project project_xxxxxxxx
ht doctor
ht repair --stage loop_x/subloop_y
ht migrate --stage loop_x/subloop_y
ht worker run --platform-url https://humanthread.cn \
  --pool-token-env HT_WORKER_POOL_TOKEN --state-dir /var/lib/humanthread

本地会生成什么

常见错误分类

ht init 同步成功不等于可以运行。可达阶段里未配置或缺失的项会由 ht doctor 与运行前检查阻断，这是刻意设计，不要用跳过检查的方式绕过。

对应界面：项目 → 项目设置

项目是工作落到实处的单位：目标、里程碑、成员、任务、文档、知识和执行配置都挂在项目下。项目也是权限边界与知识沉淀的基本单位。

1. 在「项目」新建项目，写清目标、范围与成功标准，选择所属空间。
2. 在项目里建立里程碑，明确每个阶段的产出与截止时间。
3. 邀请成员并分配角色；确定谁可以管理资料与成员。
4. 配置仓库地址与分支策略、环境变量、Worker Pool 和 Loop 绑定。
5. 需要自动化时创建定时任务；需要复用流程时保存为模板。

项目设置包含哪些分页

里程碑、任务与 Loop 的关系

1. 项目目标
2. 里程碑
3. 任务与验收标准
4. Loop 运行
5. 证据回写项目

归档或关闭项目前，先确认没有仍在运行的 Loop、未结束的定时任务和还在使用该项目的客户端或 Worker。

对应界面：项目与里程碑、项目文档、平台与公司设置

桌面客户端负责本地执行、设备绑定与终端交互；移动客户端负责查看与审批；命令行工具负责在仓库与服务器上工作。三者连接同一个部署、共用同一个账号。

1. 从下载页或 Releases 选择对应平台的产物。
2. 用同一页给出的 SHA256 校验下载完整性。
3. 首次启动填写部署地址并登录账号。
4. 按提示绑定设备：登录式绑定码 10 分钟内有效，或在设置里生成 Agent Token。
5. 绑定完成后，任务与 Loop 节点才能派发到这台设备。

当前发布的客户端

设备绑定与授权

未签名或未公证的构建只用于测试，正式分发要用自有证书重新构建。本地会话正文只保存在执行设备，平台只代理活动会话的终端字节、控制权和在线状态。

对应界面：Agent 设备与在线会话

Linux Worker 是公司执行网关管理的任务执行资源：向网关注册、上报心跳与容量、领取指派，在隔离的工作树里执行 Loop 阶段。平台只保留脱敏状态；用户不再在个人设置或项目设置中直接部署 Worker。

1. 由公司 owner/admin 在「公司管理 → 执行网关」创建或连接网关。
2. 在网关配置运行镜像、Worker 容量和执行资源；站点管理员只在「平台设置 → Worker 镜像目录」维护受控镜像。
3. 密钥和环境变量由项目环境配置交给网关托管，Worker 不直接连接平台获取长期凭据。
4. 回到公司执行网关确认节点在线与容量。
5. 在「Loop → 运行记录」确认执行目标、阶段与产物，失败时按分类处理。

必填环境变量

用 Docker 启动

docker run -d --name ht-worker \
  --env-file /etc/humanthread/worker.env \
  -v /srv/humanthread/state:/var/lib/humanthread \
  hub.luckydcms.com/library/humanthread-linux-worker:<immutable-tag>

用 Kubernetes 部署

kubectl -n <namespace> create secret generic ht-worker \
  --from-literal=HT_WORKER_POOL_TOKEN=<token> \
  --from-literal=HT_GIT_TOKEN=<git-token>
kubectl -n <namespace> apply -f worker-deployment.yaml
kubectl -n <namespace> get pods -l app=ht-worker

• Worker 和运行镜像归公司执行网关管理，不再由项目页面生成部署命令。
• 并发由网关内的 Worker 槽位与容量配置决定；运行中的任务保持同一逻辑槽位。
• 需要额外系统库或运行时（例如 GPU、图形库）时，由平台管理员发布受控运行镜像，再由网关选择。

健康状态与故障分类

公司执行网关负责公司内网的 Worker 与运行镜像。镜像只包含工具，不包含项目源码与用户凭据；日志写入前会脱敏 API Key、启动凭据、Git 凭据、Cookie 与授权头。

对应界面：公司管理 → 执行网关、平台设置 → Worker 镜像目录、Loop 运行记录

下面这张表用于产品验收：左边是文档划分，中间是对应的产品面，右边是你可以自己复核的方式。任何一个入口打不开，都说明文档与产品脱节。

本页样例使用演示数据，界面里的项目、任务与运行记录不是真实生产数据；自部署时请用自己环境里的脱敏记录复核。

文档没覆盖到的场景、需要协助排查的问题，或者想参与共建，可以通过下面两种方式联系。

@

邮箱concats@humanthread.cn账号、权限与需要跟踪的问题建议走邮件。

反馈问题时请附上页面路径、操作时间和脱敏后的错误摘要；不要在群里发送密码、Token、Cookie 或数据库连接串。