Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .scratch/agent-loop-v1/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Status: ready-for-agent
24. **离线补偿。** 恢复在线后补偿同步来源和可取得的飞书消息,并去重。具体平台权限和历史可获取范围需要验证;无法完整补回时显示缺口,而不是承诺已经无损恢复。
25. **失败处理。** 网络同步、消息投递和执行失败分别记录。可重试的传输错误按配置重试;有外部副作用的动作先核对结果。不得以失败触发无限重跑模型,也不得将未启动或投递失败的操作记为成功。
26. **交付与后续修改。** 核对草稿 PR 与任务仓库、分支和提交的关联后展示待验收状态,并保留验证结果和限制。后续反馈沿用原会话、分支和 PR。首版不自动清理群、任务数据或工作目录。
27. **运行配置。** 仓库映射、基准分支、模型与执行参数、轮询和重试设置、存储目录及凭证引用使用配置机制;密钥使用环境变量或已有凭证提供器。运行参数和项目事实不写入全局说明。Freedom 环境信息由任务侧提供,核心循环不定义其专用配置模型。
27. **运行配置。** 仓库映射、基准分支、模型与执行参数、轮询和重试设置、存储目录及凭证引用使用配置机制;应用凭证要求现由[单 JSON 配置规格 v1](../single-json-config/spec.md)取代,密钥直接存入被忽略的私有 JSON;普通系统和执行 provider 环境机制保留。运行参数和项目事实不写入全局说明。Freedom 环境信息由任务侧提供,核心循环不定义其专用配置模型。
28. **类型扩展。** 模板注册、来源分类和采集条件分别维护。未来新增类型无需重写通用会话、消息和恢复逻辑;仅修改采集类型不能让没有模板的 Feature 任务误用 Bug prompt。

## Testing Decisions
Expand Down
41 changes: 41 additions & 0 deletions .scratch/single-json-config/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
Status: ready-for-agent

# Single JSON configuration

Version: 1

## Goal and authorization

Users maintain one private JSON configuration file. The repository commits only a placeholder example. Application credentials live directly in that file.

The coordinator delegated implementation in event `single-config-implementation-v1` from task `c9edaf14-f18a-42de-841e-d963e1f520cc`. The delegation identifies the user's explicit authorization as message `om_x100b60ca1e1928a0c05c23ea7b9df56`, chat `oc_586b1866902382e0db4dff8d25c0f3f7`, sender `ou_5c280b16780ac4016c7455a276b2d95b`. This document records that relayed authorization, not a new product decision by the implementer.

## Confirmed scope

- Store `feishu.appId`, `feishu.appSecret`, and `github.token` directly in JSON. Remove their `*Env` selectors and credential environment lookup.
- Remove application dotenv loading and `--env-file`. Do not retain an optional compatibility path.
- Migrate CLI doctor, collect, run, and owned Feishu pairing and verification helpers together with examples, documentation, and tests.
- Keep normal system and provider environment mechanisms. Keep the existing conditional GitHub token requirement when collection repositories are configured.
- Keep execution hot reload. Valid edits update only execution settings. Invalid edits retain the last valid execution settings. Other settings, including credentials, require restart.
- Ignore private configuration and track only placeholder examples. Do not expose application credentials in validation errors, logs, dashboard or configuration APIs, snapshots, or reports.

## Acceptance

1. A user copies `config/example.json` to ignored `config.json`, fills direct credentials, and runs doctor without a dotenv file or application credential environment variables.
2. Collection and runtime clients receive credentials from JSON. Missing GitHub token is rejected when repositories are configured and allowed when none are configured.
3. Legacy selectors and `--env-file` fail clearly without echoing credential values. An existing dotenv file has no application effect.
4. Pair and verify helpers use the same private JSON file and do not print credentials. Pairing changes only the owner binding in that file.
5. Synthetic secrets do not appear in diagnostic output, validation failures, serialized configuration, dashboard responses, snapshots, or persisted reports.
6. Execution reload behavior and ordinary provider environment inheritance remain covered. Relevant tests, type checking, and build pass.

## Excluded scope

No live configuration or dotenv migration, deletion, or reading of actual credentials. No changes to live property lists. No deployment, service restart, merge, or unrelated coordinator intake work. No alternate credential stores or dotenv compatibility.

## Open questions

None at handoff. New scope changes require coordinator review. Network acceptance using real credentials remains outside this task's authorization.

## Comments

Implementation and independent verification are separate. The PR owner delivers the branch and evidence. The coordinator arranges an independent verifier before a merge decision.
25 changes: 22 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Agent Loop 保存项目和任务的持续上下文。用户在项目协调群交
cp config/example.json config.json
```

按下面的说明修改本机路径,并通过环境变量提供凭证。然后检查配置。
按下面的说明修改本机路径,并在私有 `config.json` 中填写凭证。然后检查配置。

```sh
npm start -- doctor --config config.json
Expand All @@ -29,7 +29,9 @@ npm install
cp config/example.json config.json
```

编辑 `config.json`,将 `feishu.userOpenId` 改为应用下的所有者 Open ID。相对路径均以配置文件所在目录为基准。
编辑私有 `config.json`,填写 `feishu.appId`、`feishu.appSecret` 和应用下的所有者 `feishu.userOpenId`。配置了采集仓库时,还需填写 `github.token`。相对路径均以配置文件所在目录为基准。

仓库只提交带占位值的 `config/example.json`。`config.json` 与 `config.json.*` 已被 Git 忽略。将私人副本保存在这些路径,或自行为其他文件名设置忽略规则,并限制文件读取权限,例如 `chmod 600 config.json`。不要把私人配置复制进日志、报告、prompt 或版本库。

正式任务共用本机 Codex daemon。Agent Loop 通过官方 `daemon version` 发现服务,只在服务未运行时调用 `daemon start`。连接失败会报告错误,断线后重新连接并核对原 Thread。Agent Loop 不停止、重启或更新 daemon,也不回退私有 App Server。

Expand Down Expand Up @@ -69,7 +71,24 @@ Agent Loop 不再使用模型选择目录。任务必须先归属到已配置项

新 Task 先保存原始任务与附件。项目协调者负责确认工程归属并通过 `claim_intake` 或 `dispatch` 派发 Worker;未归属 intake 和历史任务保持等待,不创建执行 Thread。确认归属后,协调者和 Worker 直接使用项目配置的目录,所有项目共用实例级角色执行配置。后续讨论、澄清、工程工作和恢复沿用正式 Thread。

凭证通过环境变量提供。默认名称为 `GITHUB_TOKEN`、`FEISHU_APP_ID`、`FEISHU_APP_SECRET`。配置仅保存变量名。程序加载当前目录的 `.env`,已有进程变量优先。可用 `--env-file` 指定其他文件。不要将真实凭证写入 JSON、prompt 或全局说明。
应用只从 `--config` 指定的 JSON 文件读取凭证。凭证字段直接填写值,例如:

```json
{
"github": { "token": "REPLACE_WITH_GITHUB_TOKEN" },
"feishu": {
"appId": "REPLACE_WITH_FEISHU_APP_ID",
"appSecret": "REPLACE_WITH_FEISHU_APP_SECRET",
"userOpenId": "REPLACE_WITH_YOUR_OPEN_ID"
}
}
```

这些占位值不会被视为已配置凭证。`doctor` 仅报告字段是否已填写。`collect` 只在配置采集仓库时要求 GitHub token,不要求飞书凭证;`run` 还要求飞书凭证和已绑定所有者。`status` 可在未填写凭证时读取本地状态。

应用不读取 `.env`,不接受 `--env-file`,也不支持 `tokenEnv`、`appIdEnv` 或 `appSecretEnv`。升级已有配置时,在私有 JSON 中填写直接凭证字段并移除旧字段,从服务启动参数中移除 `--env-file`。完成迁移和验收后,可由配置所有者另行处理旧环境文件。程序不会迁移或删除它。普通系统环境和 Codex provider 的环境与登录机制继续保留,JSON 凭证不会注入子进程环境。

只有 `execution` 配置会热更新。修改凭证或其他设置后,按[服务操作说明](docs/agents/operations.md)重启服务。无效编辑会保留上一次有效 execution 配置。解析后的凭证在配置导出、诊断和看板输出中被遮蔽,私有 JSON 文件本身仍保存原值。

## 飞书接入

Expand Down
6 changes: 3 additions & 3 deletions config/example.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,13 @@
}
],
"github": {
"tokenEnv": "GITHUB_TOKEN",
"token": "REPLACE_WITH_GITHUB_TOKEN",
"apiUrl": "https://api.github.com",
"requestTimeoutMs": 30000
},
"feishu": {
"appIdEnv": "FEISHU_APP_ID",
"appSecretEnv": "FEISHU_APP_SECRET",
"appId": "REPLACE_WITH_FEISHU_APP_ID",
"appSecret": "REPLACE_WITH_FEISHU_APP_SECRET",
"userOpenId": "REPLACE_WITH_YOUR_OPEN_ID"
},
"execution": {
Expand Down
4 changes: 2 additions & 2 deletions docs/agents/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

本机常驻执行服务和调试网页由同一个 `run` 进程提供,统一由 launchd 管理。后续启动、停止和重启均使用本文命令,避免另起独立后台进程争用同一数据目录。前台调试前先停止 launchd 服务。

服务定义位于 `~/Library/LaunchAgents/com.local.agent-loop.run.plist`,标签为 `com.local.agent-loop.run`。工作目录和入口以定义中的 `WorkingDirectory`、`ProgramArguments` 为准;独立 worktree 部署可以使用该 worktree 的 `dist/src/cli.js`。应用配置继续使用绝对路径 `/Users/developer/IdeaProjects/agent-loop/config.json`,凭证文件通过 `--env-file` 指定,避免因工作目录变化而读取错误位置。运行参数和环境变量保留在服务定义与应用配置中。
服务定义位于 `~/Library/LaunchAgents/com.local.agent-loop.run.plist`,标签为 `com.local.agent-loop.run`。工作目录和入口以定义中的 `WorkingDirectory`、`ProgramArguments` 为准;独立 worktree 部署可以使用该 worktree 的 `dist/src/cli.js`。应用配置继续使用绝对路径 `/Users/developer/IdeaProjects/agent-loop/config.json`,凭证直接保存在该私有 JSON 的 `github.token`、`feishu.appId` 和 `feishu.appSecret` 中。程序不读取环境凭证文件。升级服务定义时移除旧 `--env-file` 参数,并按 [README 配置说明](../../README.md#项目归属与正式任务)迁移旧字段。运行参数和普通系统或 provider 环境变量保留在服务定义中。

服务随当前用户登录加载。断开 SSH 不影响运行,进程退出后由 launchd 自动拉起。机器重启后,服务在该用户登录时启动。

Expand All @@ -16,7 +16,7 @@ launchctl print "gui/$(id -u)/com.local.agent-loop.run" | rg 'state =|pid =|last

## 修改配置后重启

修改 `config.json` 或应用代码后,执行:
只有 `execution` 配置支持热更新。修改凭证、其他配置或应用代码后,在获得对应服务操作授权后执行:

```sh
launchctl kickstart -k "gui/$(id -u)/com.local.agent-loop.run"
Expand Down
23 changes: 11 additions & 12 deletions docs/feishu-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,26 @@

## 确认当前实例与飞书应用

1. 确认目标服务的工作目录、启动参数中的 `--config` 路径和 `--env-file` 路径。未指定 `--env-file` 时,程序读取工作目录的 `.env`。本机 launchd 实例的位置与检查方法见[服务操作说明](agents/operations.md)。
2. 在该配置中找到 `feishu.appIdEnv`,读取它所指环境变量的 App ID。默认变量名为 `FEISHU_APP_ID`,`appIdEnv` 本身填写变量名。进程已有环境变量优先于 `.env`。不要用另一个终端或另一个实例的环境代替服务实际环境。
3. 登录[飞书开放平台开发者后台](https://open.feishu.cn/app),打开该 App ID 对应的应用,在“凭证与基础信息”中核对 App ID。后续权限操作均在这个应用中完成。另一实例的机器人能发文档,不代表当前应用也有权限。
1. 确认目标服务的工作目录和启动参数中的 `--config` 路径。本机 launchd 实例的位置与检查方法见[服务操作说明](agents/operations.md)。
2. 在该私有配置中找到 `feishu.appId`,在本机核对当前应用。`feishu.appSecret` 也直接保存在同一文件。不要将凭证复制到排障记录或截图中。
3. 登录[飞书开放平台开发者后台](https://open.feishu.cn/app),打开对应应用,在“凭证与基础信息”中核对 App ID。后续权限操作均在这个应用中完成。另一实例的机器人能发文档,不代表当前应用也有权限。

在项目根目录使用以下只读命令查看磁盘配置与当前终端的 App ID。将配置路径、环境文件路径换成目标实例的路径。命令只输出 App ID 和相关配置,不输出 App Secret。
在项目根目录运行以下只读命令,查看磁盘配置的凭证存在性和进度设置。将配置路径换成目标实例的路径。命令不输出凭证值。

```sh
node --import tsx --input-type=module <<'NODE'
import { loadConfig } from './src/config.ts';
process.loadEnvFile('.env');
const config = await loadConfig('config.json');
console.log(JSON.stringify({
appIdEnv: config.feishu.appIdEnv,
appId: process.env[config.feishu.appIdEnv] ?? null,
appIdConfigured: config.feishu.appId.configured,
appSecretConfigured: config.feishu.appSecret.configured,
dataDir: config.dataDir,
progress: config.feishu.progress,
}, null, 2));
NODE
```

此命令不读取运行中服务的内存配置。若凭证由服务管理器注入,需在服务定义中核对变量来源。不要将真实 App Secret 或访问令牌写入文档、JSON 配置或排障记录。
此命令不读取运行中服务的内存配置。应用不再读取 `.env` 或应用凭证环境变量,不接受 `--env-file` 与旧 `*Env` 字段。真实凭证仅写入被 Git 忽略的私有 JSON,不写入示例、文档或排障记录。

## 配置文档进度模式

Expand All @@ -33,8 +32,8 @@ NODE
```json
{
"feishu": {
"appIdEnv": "FEISHU_APP_ID",
"appSecretEnv": "FEISHU_APP_SECRET",
"appId": "REPLACE_WITH_FEISHU_APP_ID",
"appSecret": "REPLACE_WITH_FEISHU_APP_SECRET",
"userOpenId": "REPLACE_WITH_YOUR_OPEN_ID",
"progress": {
"enabled": true,
Expand Down Expand Up @@ -100,7 +99,7 @@ NODE

## 重载配置并确认目标实例

1. 使用目标配置运行 `npm start -- doctor --config config.json`。若环境文件不同,追加 `--env-file /absolute/path/to/.env`。先修正配置解析错误或缺失凭证。
1. 使用目标配置运行 `npm start -- doctor --config config.json`。应用凭证均来自该 JSON 文件。先修正配置解析错误或缺失凭证。
2. 确认服务定义中的工作目录和配置路径与刚修改的文件一致,按[服务操作说明的重启步骤](agents/operations.md#修改配置后重启)重启目标实例。不要另开一个 `run` 进程共用同一数据目录。
3. 重启后核对服务 PID、调试网页的执行服务心跳 PID 和持续更新的心跳时间。核对最新 `started` 日志的 `dataDir`、调试网页地址与目标实例一致。日志位置和状态命令见[服务操作说明](agents/operations.md)。
4. 再次运行本指南的配置查看命令,确认磁盘中的 `enabled`、`surface` 和 `documentBaseUrl`。随后用新任务群的实际文档和 Tab 完成验收。仅看到磁盘新配置或一个旧心跳,不能证明目标服务已加载新配置。
Expand Down Expand Up @@ -164,7 +163,7 @@ sqlite3 -readonly '/absolute/path/to/data/tasks.sqlite' \
| --- | --- |
| 群消息正常,但顶部没有“执行进度”Tab | 先确认 `feishu.progress.enabled: true`、`surface: "document"` 和正确的 HTTPS `documentBaseUrl`,再核对目标服务是否重载。`card` 模式只发聊天卡片。继续查文档诊断、文档进度权限及群设置是否允许机器人管理标签页。 |
| 文档或标签页接口返回 `99991672` | 这是权限不足的诊断。根据失败接口和响应中要求的权限,在当前 App ID 下添加应用身份权限,再回读实际授权。文档创建需 `docx:document`,标签页读取需 `im:chat.tabs:read` 或覆盖权限,不能用基础群信息读取成功作证明。 |
| 当前应用与正常实例的 App ID 不同 | 重新确认目标服务的 `appIdEnv`、环境文件和进程环境来源。分别进入各自应用配置权限,另一应用的已授权状态不能复用。若修改了目标实例的环境或配置,按服务操作说明重启后重新验收。 |
| 当前应用与正常实例的 App ID 不同 | 重新确认目标服务实际使用的 JSON 文件及其中的 `feishu.appId`。分别进入各自应用配置权限,另一应用的已授权状态不能复用。若修改了目标实例的凭证或其他非 execution 配置,按服务操作说明重启后重新验收。 |
| 权限已添加,但接口仍拒权 | 检查是否误选用户身份权限,以及是否尚需发布版本或管理员审批。用当前应用的应用身份回读实际授权;没有出现在已授权范围内时,返回权限管理处理,不能仅凭已添加列表判定生效。 |
| “向管理员申请授权”接口返回 `212002` | 此接口表示可申请的未授权范围为空,不能据此证明所需能力已授权。先检查所需权限是否已加入当前应用配置,再查授权状态。本次接入在尚未添加权限时遇到此码,回到权限管理添加并按后台提示开通后才恢复。接口说明见[向管理员申请授权](https://open.feishu.cn/document/application-v6/scope/apply)。 |
| 文档或 Tab 已创建,但群成员不能阅读 | 检查 `docs:permission.member:create` 与 `docs:permission.member:retrieve`,并回读文档协作者列表,确认当前 `chatId` 作为 `openchat` 成员具有 `view` 阅读权限。核对 Tab 绑定的文档 URL,使用普通群成员账号实际打开。Tab 创建成功不能证明协作者授权成功。 |
Expand Down
6 changes: 3 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@
"check": "tsc --noEmit",
"test": "tsx --test test/*.test.ts",
"benchmark:dashboard": "tsx scripts/benchmark-dashboard.ts",
"start": "tsx src/cli.ts",
"start": "node --import tsx -- src/cli.ts",
"verify:shared-codex": "npm run build && tsx scripts/verify-shared-codex.ts",
"verify:closeout": "tsx --test test/task-closeout.test.ts",
"verify:codex": "tsx scripts/verify-codex.ts",
"verify:inputs": "tsx scripts/verify-inputs.ts",
"pair:feishu": "tsx scripts/pair-feishu.ts",
"verify:feishu": "tsx scripts/verify-feishu.ts",
"pair:feishu": "node --import tsx -- scripts/pair-feishu.ts",
"verify:feishu": "node --import tsx -- scripts/verify-feishu.ts",
"verify:runtime": "tsx scripts/verify-runtime.ts",
"verify:workspace-selection": "tsx scripts/verify-workspace-selection.ts"
},
Expand Down
Loading