项目概述

gptme-agent-template 是一个用于构建自主 AI 代理工作空间的模板项目,定义了工作空间的目录结构、脚本配置和文档模板。该模板使开发者能够快速搭建具备持久记忆、任务管理、知识积累与自主执行能力的 AI 代理运行环境。

模板的核心设计理念是"工作空间即代理":每个代理拥有独立的 Git 仓库,通过结构化的目录和 Markdown 文件维护身份、任务、日志与知识,使得代理状态完全可版本化、可审计、可迁移。资料来源：ARCHITECTURE.md:1-50

快速上手

推荐通过 fork 模板的方式创建自己的代理工作空间,典型步骤如下:

1. Fork 仓库:在 GitHub 上 fork gptme-agent-template 到自己的账户下。资料来源：knowledge/forking-workspace.md:1-30

1. 清理个人内容:删除原模板的 ABOUT.md、SOUL.md 以及 journal/、tasks/ 目录中的个人内容,然后初始化新的代理身份。资料来源：knowledge/forking-workspace.md:30-60

1. 安装依赖:运行安装脚本配置 gptme、gptodo 等运行时工具。资料来源：scripts/README.md:1-30

1. 编辑身份文件:按 ABOUT.md:1-15 的模板填写代理的背景、个性、可用工具与目标。

1. 创建第一个任务:在 tasks/ 目录新建 Markdown 任务文件,使用 YAML frontmatter 标记 state、priority、tags 等元数据。资料来源：TASKS.md:30-60

核心组件

模板提供了多个核心组件支撑代理的持续运行:

任务管理 —— tasks/ 目录存放结构化任务文件,每个任务由 YAML frontmatter(包含 state、created、priority、tags 等字段)与 Markdown 正文组成。任务生命周期涵盖创建、激活、跟踪、完成/取消等阶段。资料来源：TASKS.md:50-90

日志系统 —— journal/ 按日期组织会话日志,记录任务进度、决策、反思与下一步计划;条目只追加、不覆盖,历史记录不被修改。资料来源：ARCHITECTURE.md:30-50

知识库 —— knowledge/ 目录按主题或领域组织长期信息,包含技术文档、最佳实践、项目洞察和参考资料。资料来源：ARCHITECTURE.md:50-70

课程系统 —— lessons/ 目录收纳从历史失败或经验中提炼的规则与约束,采用"主课程 + 伴随文档"的双文件结构:主课程保持 30-50 行的精炼篇幅,通过关键词自动注入上下文;伴随文档提供完整的实施背景与验证策略。资料来源：lessons/README.md:1-40

人物档案 —— people/ 目录存储代理长期交互对象的人物画像,使用统一模板记录基本信息、联系方式、兴趣技能、协作项目与沟通偏好等稳定内容。资料来源：people/templates/person.md:1-15

工作流契约 —— WORKFLOW.md 同时承担运行时配置(YAML 前置数据)与阶段指令(Markdown 正文),定义会话跟踪、上下文加载、提交后钩子等行为。资料来源：WORKFLOW.md:1-50

自主运行 —— scripts/runs/autonomous/ 提供完整的自主运行基础设施,包括 systemd timer 配置、双队列系统(手动队列为主、自动生成为后备)以及按 GREEN/YELLOW/RED 分级的安全策略。资料来源：scripts/runs/autonomous/README.md:1-50

内容分层架构

代理工作空间的内容分布在多个层级,各层具有不同的作用范围:

资料来源：ARCHITECTURE.md:60-90

模板中大部分通用文件应通过符号链接指向 gptme-contrib,代理只需更新 contrib 子模块即可获得公共组件的升级;而 ABOUT.md、SOUL.md、gptme.toml、README.md 等需要本地定制的文件则必须保留在仓库中,不应符号链接。资料来源：ARCHITECTURE.md:70-100

flowchart LR
    A[用户 fork 模板] --> B[清理个人内容]
    B --> C[编辑身份 ABOUT.md / SOUL.md]
    C --> D[创建首个任务]
    D --> E[运行 autonomous-run.sh]
    E --> F{任务是否完成?}
    F -- 否 --> G[写入 journal/]
    G --> D
    F -- 是 --> H[提交并推送]

See Also

• ARCHITECTURE —— 工作空间整体架构与内容分层
• TASKS —— 任务管理详细规范
• WORKFLOW —— 自主运行工作流契约
• Lessons System —— 课程与约束系统
• Autonomous Run —— 自主运行基础设施

工作区架构与内容分层

概述

gptme-agent-template 是一个可分叉（forkable）的 AI 代理工作区模板，用于构建可复用的长期运行代理。整个仓库围绕"分层内容 + 模板可分发"的设计理念，将通用结构与代理专属内容分离，使一次模板升级可以透明地传播到所有派生代理，而不会污染各代理的私有记忆与身份信息。

模板本身定义工作区骨架（目录布局、脚本、配置、gptme.toml 等），而 gptme-contrib 仓库以 git 子模块形式承载通用内容（包、插件、课程、pre-commit 钩子）。这种分层让代理既拥有稳定身份与长期记忆，又能在不丢失用户数据的情况下追随上游演进。

资料来源：ARCHITECTURE.md:1-40

内容分层模型

工作区采用四层内容模型，每一层都有明确的仓库归属、适用范围与内容类型，避免内容重复与过期信息累积。

资料来源：ARCHITECTURE.md:18-25

模板与 contrib 的协同关系

模板层与公共共享层通过 git 子模块和符号链接协同：模板中"通用且跨代理有用"的文件应当符号链接到 gptme-contrib，从而通过更新子模块即可接收上游变更。典型例子包括 pre-commit 钩子、课程文件、共享脚本与校验器。

不能符号链接的文件必须保留在模板内，因为它们是代理特定或需要本地定制的内容，例如 ABOUT.md、SOUL.md、gptme.toml、README.md 以及任务/日志内容。

经验法则：内容若是通用且跨代理有用，应放入 contrib 并由模板建立符号链接；若是工作区结构或身份信息，则直接放在模板中。

资料来源：ARCHITECTURE.md:27-39

核心目录结构

工作区内的目录各司其职，构成代理的长期记忆与日常操作系统：

• tasks/ — 任务文件作为单一事实来源，配合 gptodo CLI 进行状态管理。任务支持 state、priority、tags、depends 等 YAML 前置字段，并拥有从创建、激活、跟踪、完成到暂停的完整生命周期。任务通过 pre-commit 钩子校验元数据格式与链接有效性。

资料来源：TASKS.md:1-60

• journal/ — 按天组织的追加日志，路径形如 journal/YYYY-MM-DD/HHMMSS-topic.md。历史条目不可修改，确保可追溯性。日志承载任务进展、决策与反思，但不保存长期稳定信息。

资料来源：ARCHITECTURE.md:62-72

• knowledge/ — 按主题组织的技术文档、最佳实践与项目洞察，是代理的长期知识库。它区别于 lessons/ 这种以"防错约束"为核心的运行时课程。

资料来源：ARCHITECTURE.md:74-87

• people/ — 长期人员档案目录，每个档案使用 Markdown 模板（基本信息、联系方式、兴趣技能、项目合作、偏好）。档案仅保存稳定信息，易变细节（如当前任务、会话计数）应写入日志或任务文件，以避免档案自然过期。

资料来源：people/templates/person.md:1-30，ARCHITECTURE.md:88-108

• lessons/ — 课程系统采用双文件架构：主课程（30–50 行，限 100 行内）面向运行时 LLM 指导并按关键词自动加载；配套文档位于 knowledge/lessons/ 提供完整实施背景。目录按职能划分为 tools/、patterns/、social/、workflow/、strategic/。

资料来源：lessons/README.md:1-80

工作流与上下文注入

模板通过 YAML 前置元数据声明运行时配置，Markdown 正文承载代理指令，占位符（{{WORKSPACE}}、{{DATE}}、{{AGENT_NAME}}、{{CREATOR}}、{{SESSION_HASH}}）在 scripts/workflow-render.py 渲染时注入。

预构建上下文在 WORKFLOW.md 的 context.prebuilt 中列出，包含 README.md、gptme.toml、ABOUT.md、SOUL.md、ARCHITECTURE.md、TASKS.md 等基础文档；动态上下文通过 {{WORKSPACE}}/scripts/context.sh 按需生成。

资料来源：WORKFLOW.md:38-58

context.sh 整合多个组件脚本（context-journal.sh、context-workspace.sh），可通过注释开关启用/禁用，并支持代理特定的扩展点。任务元数据更新与状态流转通过 gptodo CLI 完成，例如：

gptodo edit my-task --set state active
gptodo edit my-task --add tag feature
gptodo status --compact

资料来源：scripts/README.md:1-50，TASKS.md:14-32

分叉流程与可移植代理应用

分叉流程通过 knowledge/forking-workspace.md 描述五步骤：复制工作区结构、清除个人内容、初始化新身份、更新配置、创建首个任务。被清除的内容包括日志、任务、人物档案（创建者除外）以及 ABOUT.md 中的身份信息。

资料来源：knowledge/forking-workspace.md:1-60

knowledge/portable-agent-apps.md 进一步规定"更新保留规则"：标记生成文件来源、保留用户拥有的文件、保留 tasks/、journal/、密钥与本地档案、检测漂移并在每次更新后运行校验。该规则保证分叉后的应用不会成为"fork trap"。

资料来源：knowledge/portable-agent-apps.md:88-110

自治运行基础设施

模板内置自治运行脚本（scripts/runs/autonomous/），实现 CASCADE 工作流：松散事项 → 任务选择 → 执行 → 完成。两队列系统由 state/queue-manual.md（手动维护、上下文丰富）与 state/queue-generated.md（自动生成、客观新鲜度）组成，前者为主、后者为后备。操作按安全等级分为 GREEN（代码/测试/文档）、YELLOW（社交媒体/邮件）、RED（财务/重大决策）三类。

资料来源：scripts/runs/autonomous/README.md:1-60，state/queue-generated.md:1-20

参见

• TASKS.md — 任务系统详细说明
• TOOLS.md — 工具能力清单
• WORKFLOW.md — 自治工作流契约
• lessons/README.md — 课程系统双文件架构
• knowledge/forking-workspace.md — 工作区分叉流程
• knowledge/portable-agent-apps.md — 可移植代理应用与更新保留规则

核心系统：Forking、Context、Tasks 与 Knowledge

本页介绍 gptme-agent-template 的四大核心系统：Agent Forking（智能体分叉）、Context Generation（上下文生成）、Tasks（任务管理） 与 Knowledge（知识库）。这四个系统共同构成了一个可复用、可演化、可分叉的智能体工作空间框架。

一、Agent Forking 智能体分叉

1.1 设计目的

Forking 系统允许将本模板作为基础，复制出新的智能体实例。分叉后，新智能体继承完整的基础设施（目录结构、任务系统、文档模板），同时发展自身的身份与目标 资料来源：[knowledge/agent-forking.md]。

1.2 分叉时保留与清理的内容

分叉过程遵循"结构性内容保留，个性化内容清理"的原则：

资料来源：[knowledge/forking-workspace.md]

1.3 分叉最佳实践

• 独立性：建立独特身份、设定专属目标、维护独立关系。
• 基础设施遵循：使用统一的文档模式、任务系统和知识库。
• 成长性：设置学习目标、记录改进、分享洞察。
• 更新保留规则：每次可复用应用必须声明哪些文件在更新时被保留（用户自有文件、tasks/、journal/、secrets 与本地 profile），否则会被视为"分叉陷阱" 资料来源：[knowledge/portable-agent-apps.md]。

二、Context Generation 上下文生成

2.1 上下文系统角色

上下文生成是智能体与外部世界（任务、日志、知识、人）交互的桥梁。模板通过 scripts/ 下的多个 shell 脚本（context.sh、context-git.sh、context-journal.sh、context-workspace.sh）将分散的数据聚合为统一上下文，注入到 gptme 的 prompt 中 资料来源：[ARCHITECTURE.md]。

2.2 内容分层（Content Layers）

工作空间通过 git submodule 实现多层内容共享，避免重复与内容陈旧：

flowchart TB
    A[Agent Template<br/>gptme-agent-template] -->|symlinks| B[Public Shared<br/>gptme-contrib]
    A --> C[Agent Workspace<br/>本仓库]
    B --> D[Packages, Plugins, Lessons, Hooks]
    C --> E[Identity, Journals, Tasks, Knowledge]
    F[Org Shared<br/>如 gptme-superuser] --> C
    A -.fork.-> C

通用文件（pre-commit 钩子、教训文件、共享脚本）应作为 symlink 指向 gptme-contrib，使智能体通过更新 submodule 即可获得升级 资料来源：[ARCHITECTURE.md]。

三、Tasks 任务管理

3.1 任务系统构成

任务系统是单一事实来源（single source of truth），由以下组件构成 资料来源：[ARCHITECTURE.md]：

• 任务文件：tasks/ 下的 Markdown 文件，含 YAML frontmatter。
• 任务 CLI：gptodo（可选工具，源自 gptme-contrib）。
• 进度日志：journal/ 每日记录。
• pre-commit 钩子：校验 frontmatter 格式与元数据。

3.2 任务生命周期

任务经历 创建 → 激活 → 进度跟踪 → 完成/取消 → 暂停 五个阶段。每个阶段都需要同步更新 frontmatter 中的 state 字段，并在 journal/ 中追加对应记录 资料来源：[TASKS.md]。

3.3 任务 CLI 常用命令

# 安装（如未安装）
uv tool install git+https://github.com/gptme/gptme-contrib#subdirectory=packages/gptodo

# 查看任务状态
gptodo status              # 显示所有任务
gptodo status --compact    # 仅显示新建/进行中

# 更新元数据
gptodo edit my-task --set state active
gptodo edit my-task --add tag feature

3.4 工作队列

自主运行（autonomous run）支持双队列机制：手动队列 state/queue-manual.md 是主来源，自动生成队列 state/queue-generated.md 作为回退。生成队列在每次运行前由脚本从 tasks/ 与 GitHub issues 刷新 资料来源：[scripts/runs/autonomous/README.md]。

四、Knowledge 知识库

4.1 知识库组织

知识库位于 knowledge/，按主题或领域组织子目录（如 ai/、lessons/），包含技术文档、最佳实践、项目洞察与参考资料 资料来源：[ARCHITECTURE.md]。

4.2 教训系统（Lessons）

lessons/ 目录存储结构化的经验教训，分为：

• tools/：工具特定的使用约束与陷阱。
• patterns/：跨工具通用模式。
• social/：人机/社交交互模式。
• workflow/：工作流、版本控制、文档。
• strategic/：战略决策与权衡分析。

教训格式包含必填段（Rule、Context、Detection、Pattern、Outcome、Related）与可选段（反例、变体、例外）。关键词（keywords）应使用精确的多词短语以平衡上下文污染与召回率 资料来源：[lessons/README.md]。

4.3 人员与日志

• People 目录：people/ 存储长期稳定的人物档案（身份、角色、技能、偏好），避免记录易变信息（当前任务、会话计数），后者应归入日志或任务文件 资料来源：[people/templates/person.md]。
• Journal 系统：按 journal/YYYY-MM-DD/HHMMSS-topic.md 组织，每日追加、不可修改历史记录 资料来源：[journal/templates/daily.md]。

五、自主执行工作流（衔接四大系统）

WORKFLOW.md 描述了一个四阶段自主会话流程，将上述系统串接起来 资料来源：[WORKFLOW.md]：

1. Phase 1 — 启动：加载上下文，刷新队列。
2. Phase 2 — 计划：从任务池中选取工作，遵循"总存在 Tier 3 工作"原则。
3. Phase 3 — 执行：提交真实有意义的进展；超过 10 分钟卡顿时切换任务。
4. Phase 4 — 收尾：在 journal/ 记录、提交、推送 origin。

See Also

• ARCHITECTURE.md — 完整架构说明
• TOOLS.md — 工具集成
• Release v0.3 Notes — 任务结构简化与 CI
• Release v0.4 Notes — 上下文生成改进

自主工作流与多后端部署

概述

gptme-agent-template 是一个可分叉（forkable）的 AI 代理工作区模板，其核心目标是让同一个"代理大脑"仓库能够在多种代理运行时（agent harness）上以自主会话（autonomous session）的模式持续运行。本页聚焦于该模板如何通过 WORKFLOW.md 与 scripts/runs/autonomous/ 下的脚本，将任务队列、阶段化会话、双队列调度与安全分类组合成一个可在生产环境中通过 systemd 调度的无人值守工作流。

模板的整体架构在 ARCHITECTURE.md 中被定义为"可分叉代理架构"，并把任务系统（TASKS.md）、日志系统、共享内容层和本主题——自主执行循环——清晰地串联起来。

多后端 Harness 配置

WORKFLOW.md 是整个仓库版本化的"自治工作流契约"，采用 YAML front matter + Markdown 正文的形式，以便同一份文档同时被多种运行时解析。Front matter 中关键的 harness 字段定义了支持的后端：

harness:
  allowed:
    - gptme
    - claude-code
  default: gptme
  # model_routing: customize per-harness model in your fork, e.g.:
  #   gptme: "openrouter/anthropic/claude-3.5-sonnet"
  #   claude-code: "claude-sonnet-4-5"

资料来源：WORKFLOW.md:9-18

这意味着分叉者可以在同一个工作区里通过注释切换默认模型，或者在 fork 中为每个 harness 单独配置模型路由（model_routing）。同一文件还规定了会话级默认值：

资料来源：WORKFLOW.md:1-39

{{WORKSPACE}}、{{DATE}}、{{AGENT_NAME}}、{{CREATOR}}、{{SESSION_HASH}} 等占位符由 scripts/workflow-render.py 在运行时注入，从而让同一份 WORKFLOW.md 文档能在不同环境与不同 harness 之间无缝迁移。

自主执行循环与会话阶段

scripts/runs/autonomous/README.md 描述了由 autonomous-run.sh 驱动的 CASCADE 工作流，其要点是"先处理零散工作，再选择新任务，再执行"。运行时会从两个队列中选择任务来源：

• 手工队列 state/queue-manual.md：主要来源，由人/代理维护，包含会话推理、依赖关系、策略备注。
• 自动生成队列 state/queue-generated.md：当手工队列为空时回退使用，会在每次运行前从任务文件和 GitHub Issues 重新生成。

flowchart TD
    A[systemd timer 触发] --> B[autonomous-run.sh]
    B --> C{手工队列<br/>是否为空?}
    C -- 否 --> D[读取 queue-manual.md]
    C -- 是 --> E[刷新 queue-generated.md]
    D --> F[CASCADE: 零散工作]
    E --> F
    F --> G[任务选择]
    G --> H[Phase 3: 执行<br/>代码/文档/提交]
    H --> I[Phase 4: 完成]
    I --> J[journal/YYYY-MM-DD/<br/>autonomous-session-HASH.md]
    I --> K[git push origin HEAD]
    J --> L[post_commit hook]

资料来源：scripts/runs/autonomous/README.md

WORKFLOW.md 的 Phase 3 与 Phase 4 进一步规范了"执行"与"收尾"两阶段：执行阶段要求真实提交（make typecheck、make test、更新 tasks/ 元数据），并规定"卡住超过 10 分钟则切换到下一任务"；完成阶段必须把进展写入 journal/{{DATE}}/autonomous-session-{{SESSION_HASH}}.md、使用约定式提交（conventional commits）并 git push origin HEAD，同时 hooks.post_commit 配置了推送钩子以保持远端同步。

资料来源：WORKFLOW.md

安全分类与运维监控

自主代理最大的风险是越权执行敏感操作。模板通过三色安全分类对操作进行分级：

资料来源：scripts/runs/autonomous/README.md

模板同时内置 systemd --user 调度与监控命令，例如 systemctl --user status agent-autonomous.timer、journalctl --user -u agent-autonomous.service --since "1 hour ago" 与 -f 实时跟踪。开发者可在 OnCalendar 中以 *:0/15（每 15 分钟）或 Mon-Fri *-*-* 08:00:00（工作日 8 点）等方式自定义频率，并通过 SCRIPT_TIMEOUT（如每小时 3000 秒、每两小时 6000 秒）匹配调度粒度。

共享内容与多后端的协同

为了让同一个工作区在 gptme 与 claude-code 等不同 harness 上都拿到一致上下文，ARCHITECTURE.md 定义了四层内容模型：

资料来源：ARCHITECTURE.md

模板内的多数文件应是 gptme-contrib 的符号链接——这样代理只需更新 contrib 子模块即可获得最新修复；而 ABOUT.md、SOUL.md、gptme.toml、README.md、任务/日志内容因为与代理身份强相关，必须留在工作区本地。这种"模板 + contrib + 本地"的分层，配合 WORKFLOW.md 的多 harness 声明和 scripts/runs/autonomous/ 的 CASCADE 循环，就构成了模板在多后端环境下保持一致行为的根基。

常见故障与排错

scripts/runs/autonomous/README.md 列出了几个高频问题：

• 脚本立即退出：检查 WORKSPACE 路径是否存在、gptme 是否在 PATH 中，并查看日志首条错误。
• git pull 失败：确认 SSH key 配置、网络连通性以及远端仓库访问权限。
• 超时问题：上调 SCRIPT_TIMEOUT，或在会话级别降低 session.default_timeout。

在 make test 阶段，v0.4 发布说明修复了"macOS 上 date 命令不工作"的问题（PR #17），表明跨平台执行时的 shell 兼容性是常见踩点。社区演进路径上，从 v0.1 到 v0.4，模板逐步引入 CI 校验、改进上下文生成（PR #16 之后的 feat(scripts): improve context generation）并简化任务结构，使得多后端部署的稳定性持续提升。

资料来源：v0.4 release notes

参见

• ARCHITECTURE.md — 整体架构与内容分层
• TASKS.md — 任务系统与 gptodo CLI
• scripts/README.md — 脚本索引与自治运行入口
• skills/README.md — 可复用技能与渐进式披露
• README.md — 模板总览与 Forking 说明

Pitfall Log / 踩坑日志

项目：gptme/gptme-agent-template

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:891962756 | https://github.com/gptme/gptme-agent-template | host_targets=claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:891962756 | https://github.com/gptme/gptme-agent-template | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:891962756 | https://github.com/gptme/gptme-agent-template | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:891962756 | https://github.com/gptme/gptme-agent-template | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:891962756 | https://github.com/gptme/gptme-agent-template | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:891962756 | https://github.com/gptme/gptme-agent-template | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:891962756 | https://github.com/gptme/gptme-agent-template | release_recency=unknown