# https://github.com/gptme/gptme-agent-template 项目说明书

生成时间：2026-06-13 15:53:23 UTC

## 目录

- [Introduction & Quick Start](#page-1)
- [Workspace Architecture & Content Layers](#page-2)
- [Core Systems: Forking, Context, Tasks & Knowledge](#page-3)
- [Autonomous Workflow & Multi-Backend Deployment](#page-4)

<a id='page-1'></a>

## Introduction & Quick Start

### 相关页面

相关主题：[Workspace Architecture & Content Layers](#page-2), [Core Systems: Forking, Context, Tasks & Knowledge](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ARCHITECTURE.md](https://github.com/gptme-agent-template/blob/main/ARCHITECTURE.md)
- [ABOUT.md](https://github.com/gptme-agent-template/blob/main/ABOUT.md)
- [TASKS.md](https://github.com/gptme-agent-template/blob/main/TASKS.md)
- [WORKFLOW.md](https://github.com/gptme-agent-template/blob/main/WORKFLOW.md)
- [lessons/README.md](https://github.com/gptme-agent-template/blob/main/lessons/README.md)
- [knowledge/forking-workspace.md](https://github.com/gptme-agent-template/blob/main/knowledge/forking-workspace.md)
- [scripts/README.md](https://github.com/gptme-agent-template/blob/main/scripts/README.md)
- [scripts/runs/autonomous/README.md](https://github.com/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md)
- [state/queue-generated.md](https://github.com/gptme-agent-template/blob/main/state/queue-generated.md)
- [people/templates/person.md](https://github.com/gptme-agent-template/blob/main/people/templates/person.md)
</details>

# Introduction & Quick Start

## 项目概述

`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]()

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

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

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

5. **创建第一个任务**:在 `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]()

## 内容分层架构

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

| 层级 | 仓库 | 作用范围 | 内容类型 |
|------|------|----------|----------|
| 代理模板 | gptme-agent-template | 所有代理 | 工作空间结构、脚本、配置、模板 |
| 公共共享 | gptme-contrib | 所有 gptme 用户 | 软件包、插件、课程、pre-commit 钩子 |
| 组织共享 | (如 gptme-superuser) | 组织内代理 | 战略、人物、运营、流程 |
| 代理工作空间 | (当前仓库) | 单个代理 | 身份、日志、任务、知识 |

资料来源：[ARCHITECTURE.md:60-90]()

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

```mermaid
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](./ARCHITECTURE) —— 工作空间整体架构与内容分层
- [TASKS](./TASKS) —— 任务管理详细规范
- [WORKFLOW](./WORKFLOW) —— 自主运行工作流契约
- [Lessons System](./lessons/README) —— 课程与约束系统
- [Autonomous Run](./scripts/runs/autonomous/README) —— 自主运行基础设施

---

<a id='page-2'></a>

## Workspace Architecture & Content Layers

### 相关页面

相关主题：[Introduction & Quick Start](#page-1), [Core Systems: Forking, Context, Tasks & Knowledge](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md)
- [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md)
- [TOOLS.md](https://github.com/gptme/gptme-agent-template/blob/main/TOOLS.md)
- [gptme.toml](https://github.com/gptme/gptme-agent-template/blob/main/gptme.toml)
- [ABOUT.md](https://github.com/gptme/gptme-agent-template/blob/main/ABOUT.md)
- [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md)
- [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md)
- [knowledge/portable-agent-apps.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/portable-agent-apps.md)
- [lessons/README.md](https://github.com/gptme/gptme-agent-template/blob/main/lessons/README.md)
- [scripts/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/README.md)
- [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md)
- [people/templates/person.md](https://github.com/gptme/gptme-agent-template/blob/main/people/templates/person.md)
- [state/queue-generated.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-generated.md)
</details>

# 工作区架构与内容分层

## 概述

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

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

资料来源：[ARCHITECTURE.md:1-40]()

## 内容分层模型

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

| 层级 | 仓库 | 适用范围 | 内容 |
|------|------|----------|------|
| **代理模板** | `gptme-agent-template` | 所有代理 | 工作区结构、脚本、配置、模板 |
| **公共共享** | `gptme-contrib` | 所有 gptme 用户 | 包、插件、课程、pre-commit 钩子 |
| **组织共享** | 例如 `gptme-superuser` | 组织内代理 | 战略、人员、运营、流程 |
| **代理工作区** | 当前仓库 | 单个代理 | 身份、日志、任务、知识库 |

资料来源：[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 完成，例如：

```sh
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](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md) — 任务系统详细说明
- [TOOLS.md](https://github.com/gptme/gptme-agent-template/blob/main/TOOLS.md) — 工具能力清单
- [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) — 自治工作流契约
- [lessons/README.md](https://github.com/gptme/gptme-agent-template/blob/main/lessons/README.md) — 课程系统双文件架构
- [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md) — 工作区分叉流程
- [knowledge/portable-agent-apps.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/portable-agent-apps.md) — 可移植代理应用与更新保留规则

---

<a id='page-3'></a>

## Core Systems: Forking, Context, Tasks & Knowledge

### 相关页面

相关主题：[Introduction & Quick Start](#page-1), [Workspace Architecture & Content Layers](#page-2), [Autonomous Workflow & Multi-Backend Deployment](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [knowledge/agent-forking.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/agent-forking.md)
- [knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md)
- [knowledge/portable-agent-apps.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/portable-agent-apps.md)
- [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md)
- [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md)
- [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md)
- [lessons/README.md](https://github.com/gptme/gptme-agent-template/blob/main/lessons/README.md)
- [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md)
- [journal/templates/daily.md](https://github.com/gptme/gptme-agent-template/blob/main/journal/templates/daily.md)
- [people/templates/person.md](https://github.com/gptme/gptme-agent-template/blob/main/people/templates/person.md)
- [state/queue-generated.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-generated.md)
- [ABOUT.md](https://github.com/gptme/gptme-agent-template/blob/main/ABOUT.md)
</details>

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

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

## 一、Agent Forking 智能体分叉

### 1.1 设计目的

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

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

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

| 保留（Stays） | 清理（Cleared） |
|---|---|
| 目录结构、任务管理、文档模板 | `journal/` 日志条目 |
| `ARCHITECTURE.md`、`TOOLS.md` | `tasks/` 中已有的任务内容 |
| 技术性 `knowledge/` 内容（如 AI/ML） | `ABOUT.md`（重新编写） |
| 工具配置 | `people/`（除创建者外的关系档案） |
| — | `projects/` 项目链接 |

[资料来源：[knowledge/forking-workspace.md](https://github.com/gptme/gptme-agent-template/blob/main/knowledge/forking-workspace.md)]

### 1.3 分叉最佳实践

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

### 2.2 内容分层（Content Layers）

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

```mermaid
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
```

| 分层 | 仓库 | 范围 | 典型内容 |
|---|---|---|---|
| Agent Template | gptme-agent-template | 所有智能体 | 工作空间结构、脚本、配置、模板 |
| Public Shared | gptme-contrib | 所有 gptme 用户 | 包、插件、教训、pre-commit 钩子 |
| Org Shared | （如 gptme-superuser） | 组织智能体 | 战略、人员、运营、流程 |
| Agent Workspace | 本仓库 | 单一智能体 | 身份、日志、任务、知识 |

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

## 三、Tasks 任务管理

### 3.1 任务系统构成

任务系统是单一事实来源（single source of truth），由以下组件构成 [资料来源：[ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md)]：

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

### 3.2 任务生命周期

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

### 3.3 任务 CLI 常用命令

```sh
# 安装（如未安装）
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](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md)]。

## 四、Knowledge 知识库

### 4.1 知识库组织

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

### 4.2 教训系统（Lessons）

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

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

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

### 4.3 人员与日志

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

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

WORKFLOW.md 描述了一个四阶段自主会话流程，将上述系统串接起来 [资料来源：[WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md)]：

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

## See Also

- [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) — 完整架构说明
- [TOOLS.md](https://github.com/gptme/gptme-agent-template/blob/main/TOOLS.md) — 工具集成
- [Release v0.3 Notes](https://github.com/gptme/gptme-agent-template/releases/tag/v0.3) — 任务结构简化与 CI
- [Release v0.4 Notes](https://github.com/gptme/gptme-agent-template/releases/tag/v0.4) — 上下文生成改进

---

<a id='page-4'></a>

## Autonomous Workflow & Multi-Backend Deployment

### 相关页面

相关主题：[Workspace Architecture & Content Layers](#page-2), [Core Systems: Forking, Context, Tasks & Knowledge](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [WORKFLOW.md](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md)
- [ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md)
- [scripts/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/README.md)
- [scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md)
- [state/queue-generated.md](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-generated.md)
- [skills/README.md](https://github.com/gptme/gptme-agent-template/blob/main/skills/README.md)
- [TASKS.md](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md)
- [README.md](https://github.com/gptme/gptme-agent-template/blob/main/README.md)
</details>

# 自主工作流与多后端部署

## 概述

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

模板的整体架构在 [`ARCHITECTURE.md`](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) 中被定义为"可分叉代理架构"，并把任务系统（[`TASKS.md`](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md)）、日志系统、共享内容层和本主题——自主执行循环——清晰地串联起来。

## 多后端 Harness 配置

[`WORKFLOW.md`](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md) 是整个仓库版本化的"自治工作流契约"，采用 YAML front matter + Markdown 正文的形式，以便同一份文档同时被多种运行时解析。Front matter 中关键的 `harness` 字段定义了支持的后端：

```yaml
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](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md)

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

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `session.default_timeout` | `45` | 单次会话超时（分钟） |
| `session.commit_style` | `conventional` | 提交信息风格 |
| `session.require_precommit` | `true` | 提交前必须运行 pre-commit |
| `tracker.kind` | `gptodo` | 任务跟踪器后端 |
| `tracker.tasks_dir` | `{{WORKSPACE}}/tasks` | 任务文件根目录 |
| `workspace.journal_dir` | `{{WORKSPACE}}/journal/{{DATE}}` | 日志目录（按日期分目录） |
| `context.prebuilt` | README/ABOUT/SOUL/ARCHITECTURE/TASKS 等 | 预加载到上下文的文件 |
| `context.dynamic_cmd` | `{{WORKSPACE}}/scripts/context.sh` | 动态上下文生成命令 |

资料来源：[WORKFLOW.md:1-39](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md)

`{{WORKSPACE}}`、`{{DATE}}`、`{{AGENT_NAME}}`、`{{CREATOR}}`、`{{SESSION_HASH}}` 等占位符由 [`scripts/workflow-render.py`](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/) 在运行时注入，从而让同一份 `WORKFLOW.md` 文档能在不同环境与不同 harness 之间无缝迁移。

## 自主执行循环与会话阶段

[`scripts/runs/autonomous/README.md`](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md) 描述了由 `autonomous-run.sh` 驱动的 **CASCADE 工作流**，其要点是"先处理零散工作，再选择新任务，再执行"。运行时会从两个队列中选择任务来源：

- **手工队列** [`state/queue-manual.md`](https://github.com/gptme/gptme-agent-template/blob/main/scripts/runs/autonomous/README.md)：主要来源，由人/代理维护，包含会话推理、依赖关系、策略备注。
- **自动生成队列** [`state/queue-generated.md`](https://github.com/gptme/gptme-agent-template/blob/main/state/queue-generated.md)：当手工队列为空时回退使用，会在每次运行前从任务文件和 GitHub Issues 重新生成。

```mermaid
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](https://github.com/gptme/gptme-agent-template/blob/main/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](https://github.com/gptme/gptme-agent-template/blob/main/WORKFLOW.md)

## 安全分类与运维监控

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

| 颜色 | 类别 | 建议 |
|------|------|------|
| 绿色 GREEN | 代码、测试、文档、重构 | 自主执行 |
| 黄色 YELLOW | 社交媒体、邮件 | 遵循既有模式 |
| 红色 RED | 财务、重大决策 | 升级到人类 |

资料来源：[scripts/runs/autonomous/README.md](https://github.com/gptme/gptme-agent-template/blob/main/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`](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md) 定义了四层内容模型：

| 层 | 仓库 | 作用范围 |
|----|------|----------|
| 代理模板 | `gptme-agent-template` | 所有代理（结构、脚本、配置） |
| 公共共享 | `gptme-contrib` | 所有 gptme 用户（hooks、lessons、scripts） |
| 组织共享 | `gptme-superuser` 等 | 组织内代理（战略、人员、流程） |
| 代理工作区 | 当前仓库 | 单个代理（身份、任务、知识） |

资料来源：[ARCHITECTURE.md](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md)

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

## 常见故障与排错

[`scripts/runs/autonomous/README.md`](https://github.com/gptme/gptme-agent-template/blob/main/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](https://github.com/gptme/gptme-agent-template/releases/tag/v0.4)

## 参见

- [ARCHITECTURE.md — 整体架构与内容分层](https://github.com/gptme/gptme-agent-template/blob/main/ARCHITECTURE.md)
- [TASKS.md — 任务系统与 gptodo CLI](https://github.com/gptme/gptme-agent-template/blob/main/TASKS.md)
- [scripts/README.md — 脚本索引与自治运行入口](https://github.com/gptme/gptme-agent-template/blob/main/scripts/README.md)
- [skills/README.md — 可复用技能与渐进式披露](https://github.com/gptme/gptme-agent-template/blob/main/skills/README.md)
- [README.md — 模板总览与 Forking 说明](https://github.com/gptme/gptme-agent-template/blob/main/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: gptme/gptme-agent-template; human_manual_source: deepwiki_human_wiki -->