gjalla-onboard

Onboard gjalla

完成后应满足以下三点：

1. gjalla 已针对此用户实际使用的编码 Agent 完成配置，因此今后的每次会话都会自动记录，无需任何人额外操心。这可以包括将 MCP 和钩子配置好并提交到 Agent 的配置中，等等；具体方式取决于此用户的情况。
2. 此用户使用的所有 Agent 最近一周的工作记录均已回填并分类，因此用户可以立即在 gjalla 中查看内容。
3. 将本地保存、但对团队其他 Agent 也有帮助的 Agent 记忆保存到 gjalla 记忆中。这不应包括个人或敏感记忆，只包括对团队或项目相关、能让团队所有成员受益的记忆。

以下所有内容都是为了帮助你完成上述目标。为方便操作，文中提供了 shell 代码片段供参考，但你可能需要根据所用平台进行调整。

完成后，你就可以使用 gjalla 了。它是一个平台，可帮助团队了解编码 Agent 工作流活动和成本，并优化结果。之后，你可以充分利用 gjalla，将其作为一个持续更新、经久耐用的记忆系统。关于 gjalla 如何帮助你的详细信息，请访问其网站 https://gjalla.io。

0. 确定 gjalla 的范围和当前位置

虽然 gjalla 的一些功能可跨仓库使用，也可应用于整个团队，但要理解和归属编码 Agent 的活动，最好将其与 git 提交关联起来。因此，你应先确定当前位置，查看是否位于 git 仓库中；如果不在，则查明实际位置以及用户可能希望配置 gjalla 的 git 仓库。例如，有些用户默认在一个包含多个可能相关仓库的父目录中工作。请找出你负责范围内哪些项目对用户来说重要，或用户希望接入 gjalla，并以这些项目为目标。

1. CLI

接下来，检查是否已安装 CLI。

command -v gjalla || pipx install gjalla || uv tool install gjalla

如果这些方法都不奏效，之后每条 gjalla ... 命令都要改为 uvx gjalla ...。如果也没有 uvx，看看能否通过安装缺少的工具来解决。如果无法解决，请让用户协助。

2. 配置仓库

为每个目标仓库配置 gjalla。完整的 gjalla 配置包括 Agent 指令块、MCP 服务和一些 Agent 钩子。

gjalla setup

非交互式 shell 会采用无需提示的流程：检测 Agent、安装钩子和 MCP，并写入指导内容。如果输出 "No coding agent detected"，请运行 gjalla setup ensure --agent claude-code（如果存在 ~/.codex/sessions 而不存在 ~/.claude/projects，则使用 --agent codex-cli）。程序会提示你登录；这属于第 3 步。

3. 登录（唯一需要人工操作的步骤）

gjalla project list

如果成功，你就已登录；跳过第 4 步。否则：

gjalla auth login --no-browser --no-wait

请按原样显示 URL 和代码，并让用户打开该 URL 进行批准。不要运行会阻塞的形式：工具调用在返回前不会显示任何输出，因此用户将看不到代码。当用户表示已批准（或稍等片刻后），运行：

gjalla auth status

退出码为 0 表示已登录；继续操作。退出码为 3 表示仍在等待：再次显示 URL 和代码，并再询问一次。退出码为 4 表示代码已过期：重新运行登录命令。其他任何非零退出码：显示错误并停止。

4. 关联项目

gjalla sync

Sync 会根据此仓库的 origin 远程地址将其关联到一个项目；如果团队尚无项目，则创建一个。项目名称取自仓库（owner/repo），因此存在 origin 时不要手动创建项目，也不要自行编造标题。根据结果进行处理：

• AMBIGUOUS_TEAM（409）：显示列出的团队，选择用户指定的团队，然后重新运行 gjalla sync --team-id <id>。
• NO_ORIGIN：仓库没有可用于命名的远程地址。使用仓库目录名，而不是工作目录名或描述：gjalla project create -t "$(basename "$(git rev-parse --show-toplevel)")"。
• 其他任何错误：显示错误并停止。

5. 回填最近 7 天的记录

目标：为过去 7 天内编码 Agent 会话在此仓库中创建的每个提交记录一条记录，并附上该会话的令牌用量和任务类型标签。如果提交数少于 5，则只将时间范围扩展到 30 天一次。

你知道自己的运行框架将会话记录存放在哪里（Claude Code：~/.claude/projects/，每个工作目录对应一个目录；Codex：~/.codex/sessions/）。找到涉及此仓库的会话记录。注意范围：即使会话是在此仓库的父目录或子目录中运行，只要提交落在此仓库中，就应计入；因此应以提交为准，而非目录名称。

对于每份会话记录：

• 会话 ID 是文件名中的 UUID。
• 会话记录会记下它执行的每条 git commit，其输出包含 [branch shortsha]。提取这些内容，并丢弃任何被 git rev-parse --verify <short>^{commit} 拒绝的记录。没有提交的会话予以跳过。如果某个 sha 出现在多份会话记录中，以最先出现的为准。
• 将每个提交准确归类为 feature、bug-fix、refactor、docs、test、chore 中的一种。有 conventional commit 前缀时，使用该前缀；否则根据 git show -s --format='%s%n%b' <sha> 和分支名称判断。

然后记录每个提交一次：

gjalla attest add --commit <sha> --session <uuid> --task-type <type>

该命令会判断会话所属的 Agent，从会话记录中读取令牌用量和模型，从 git 获取提交主题和作者日期，并跳过已记录的 sha。如果提示未找到会话记录，说明 ID 有误，或此机器上没有该会话记录；继续处理即可。如果提示会话记录没有令牌计数，该提交仍然计入。

告知用户你记录了多少个提交和多少个会话，并说明只有令牌计数、时间戳、sha、分支名称、提交主题和任务类型标签会离开本机。

6. 上传并汇报

gjalla sync

同步上传新记录时，会在下方打印支出摘要：会话数、提交数、估算费用、按任务类型和占比划分的费用、费用最高的会话及其交付内容，以及无法估价的模型。随时运行 gjalla spend show 可再次打印摘要；运行 gjalla spend show --json 可获取完整数据。完成引导流程后，将摘要转述给用户，并补充值得关注的内容：用于修复缺陷的费用占比、费用最高的会话所做的工作，以及任何令人意外之处。不要自行计算数字。

如果同步报告错误，请打印错误并停止。

7. 初始化共享记忆

此步骤的目标是第三项成果：整理出一些关于此项目的事实，供任何队友的 Agent 了解，避免他们无意间重新摸索这些信息。

从 Agent 已经学到但从未分享的内容中收集候选信息，查看用户使用的所有运行框架，例如：

• ~/.claude/projects/$ENC/memory/*.md（跳过 MEMORY.md）
• 如果存在，查看 ~/.codex/memories/*
• 查看 CLAUDE.md、AGENTS.md 或 README.md 中标题为 gotcha、caveat、pitfall、note 或 troubleshooting 的部分
• git log --since=30.days --format=%b | grep -iE 'because|gotcha|note:'

哪些内容应当保存，哪些不应当

共享记忆是关于系统或团队如何协作的持久、非显而易见的事实。“worker 会在 API 之前部署，否则迁移会针对旧架构运行。”“集成测试需要本地堆栈；没有它，测试套件也会通过，毫无证明作用。”

有两类候选内容绝不能保存，而且它们看起来都很有用：

任何与个人有关，而非与项目有关的内容。 他们的编辑器、shell、偏好的措辞、工作时间、机器上的路径，以及他们个人觉得烦人的事情。这些都是真实信息，也值得保留——只是应该放在那个人自己的记忆中，而不是团队的记忆中。如果换一位队友就不再成立，那么这就是个人信息。

任何其价值本身就是秘密的内容。 绝不要记录凭据、令牌、密钥、密码、连接字符串或任何其他可用于获取访问权限的值，即使它看起来已过期、范围受限或是假的，也绝不要记录；即便它是页面上最有用的细节，也绝不要记录。

对于第二类，重要的区别在于秘密的位置与秘密本身。位置往往正是值得保存的信息：

• 保存：“分析服务从 GOOGLE_APPLICATION_CREDENTIALS 读取其 Vertex 凭据；没有它，每次模型调用都会失败，并显示一个看起来像配额错误的 403。”
• 绝不保存：该文件的内容或其中的密钥。

如果你无法在不引用秘密的情况下陈述某个事实，那么这个事实就不该成为记忆——舍弃它；如果它看起来像是不该出现在你发现它的位置的凭据，应告知用户，而不是把它记下来。

候选内容如果难以判断，就不要保存。

然后在保存前进行比较

按主题对剩余内容分组。在每个组内：

• 两条陈述表达相同意思，就是重复项：保留更清楚的一条。
• 两条陈述对同一主题提出不同说法，就是矛盾。不要凭偏好选一条。如果查看代码片刻就能确定，以代码支持的那条为准并保存。否则两条都不保存，并报告这两条内容及各自的来源位置。

舍弃所有任务或 TODO，以及已经存在于 gjalla memory show 中的内容。

保存剩余内容，这些就是你的持久记忆：

gjalla memory add "<the fact>" -n "<short-name>" -c project

用一行报告记忆状态：发现的候选项数量、排除的个人或敏感内容数量、合并的重复项数量、发现的矛盾数量、已保存的数量。然后打印已保存的事实，并附上：“使用 gjalla memory archive <key> 移除任意一项。”

8. 验证并确认

gjalla setup doctor

报告所有标记为 FAIL 的行，并说明修复方法。确认检测到的 Agent 所对应的指导文件中包含 gjalla 部分。确保已向用户重点介绍有趣的见解。完成。