kingkongshot/pensieve

开发者: kingkongshot许可证: MIT2.5k

将 Pensieve 的中文开发/发布分支同步到英文主分支。在 Pensieve 仓库中，当用户要求将 zh 或 experimental 同步到 main、发布英文分支、翻译 Pensieve README/工具规范/模板/SKILL.md，或运行从 zh 到 main 的发布流程时使用。不适用于常规项目本地化或通用 i18n。

关于Skill 介绍README常见问题

典型用途

只靠通用对话时，和「pensieve」相关的Agent 技能容易每次说法不同，结果也不稳定。

pensieve用来处理这类Agent 技能。仓库说明没有给出更细的适用边界，因此这里只按名称和任务类型「Agent 技能」来写。输入侧暂按文本理解，交付侧暂按文本理解。它不替代你读仓库里的 SKILL.md，只帮你在安装前判断这件事值不值得交给 Agent。

何时会触发

当用户的说法接近这项技能的名称或任务时会匹配。用户用名称或接近的说法点名这项技能，或描述与它相同的任务。

请用pensieve处理这件事
帮我做一次Agent 技能
按pensieve的方式完成，不要换一套通用步骤

若用户只是随口提到相关词、并不要求现在就做，未必应该触发。具体匹配句子以 GitHub 上的 SKILL.md 为准。

安装前注意

安装前先看它会动哪些材料：当前能确定的输入是文本，输出是文本。是否会改文件、跑命令或访问网络，仓库说明里没有写死，不能从名称推断。

权限、副作用和适用范围都以该仓库的 SKILL.md 为准。涉及生产数据、账号或对外发布时，先在小范围试一次，再决定是否常用。

重要提示：本站仅作 Skill 资源导航与收录，正文以 GitHub 原仓库为准，版权归原项目所有。

文件

索引更新于 11/2/2026, 7:48:55 AM

原文译文

.codex/skills/pensieve-sync-to-main/SKILL.md4.5 KB当前在 GitHub 查看 ↗

.codex/skills/pensieve-sync-to-main/agents/openai.yaml220 B在 GitHub 查看 ↗

Pensieve Sync to Main

Use only inside the Pensieve repository itself.

This skill syncs changes from experimental or zh into main, preserves contributor history, and ensures main remains the English release branch. This is a maintainer release flow, not a default pipeline that should be seeded into every Pensieve user project.

Hard Rules

main must remain English-only and release-grade.
Preserve source-branch commit history; do not squash contributor history unless the user explicitly asks.
Code logic must stay identical across language branches; only text content may differ.
Do not translate code identifiers, paths, protocol names, command names, frontmatter keys, or Markdown link targets unless the branch rules below explicitly require it.
When the worktree has unrelated local changes, do not run destructive git cleanup commands.

Branch Strategy

experimental: development branch
zh: Chinese release branch
main: English release branch

Default source branch is zh unless the user explicitly specifies experimental. Default remote is kingkongshot.

Translation Scope

Chinese content in these files must be translated into English:

README.md
SKILL.md
.src/references/*.md
.src/tools/*.md
.src/templates/**/*.md

These files are synced directly by default; translate only if user-visible Chinese appears on the English branch:

Scripts and code
JSON/YAML configuration
Deleted files
Binary assets

Workflow

1. Confirm scope

Check current state:

git branch --show-current
git status --short
git remote -v

Confirm source branch:

git fetch kingkongshot
git diff --stat main..kingkongshot/<source-branch>

Classify changed files as: needs translation, direct sync, deletion, binary/config.
If the worktree has unrelated local changes, report them before switching branches.

2. Create sync branch

Start from latest main:

git checkout main
git pull kingkongshot main
git checkout -b sync/zh-to-main-<date>[-topic]

Merge the source branch to preserve history:

git merge kingkongshot/<source-branch> -X theirs --no-edit

If the user explicitly asks to sync only a few files, use targeted checkout:
```
git checkout kingkongshot/<source-branch> -- <file>
```
Resolve conflicts before translating.

3. Translate

Rules:

Translate all Chinese prose into English.
Preserve Markdown structure, frontmatter, code blocks, command syntax, and HTML tags.
Preserve intentionally bilingual matching regexes, such as the Exploration Reduction compatibility check.
Installation commands in English-branch docs must use git clone -b main, not git clone -b zh.
English-branch language-switch links should point back to the Chinese README.
Translate Chinese strings in scripts only when they are user-visible on the English branch.

Validation:

rg -n --pcre2 '\p{Han}' README.md SKILL.md .src docs

After translation, results may only include intentionally retained Chinese, such as language-switch links or bilingual regexes.

4. Validate, commit, and open PR

Run checks that exist in the current repository:
```
git diff --check
```

Commit:

git add -A
git commit -m "translate: sync <source-branch> to main"

Push and create a PR:

git push kingkongshot sync/zh-to-main-<date>[-topic]
gh pr create --repo kingkongshot/Pensieve --base main --head sync/zh-to-main-<date>[-topic]

Unless the user explicitly delegated the full release flow, ask for confirmation before merging the PR.

Failure Fallback

Merge conflicts remain: stop, list conflict files, and resolve them directly. Prefer source-branch content, then translate.
Chinese remains after translation: inspect each item, translate it, or explain why it is intentionally retained.
Push rejected: fetch, rebase the sync branch onto latest kingkongshot/main, then retry.
GitHub CLI authentication fails: report the exact authentication error; do not switch to an unknown remote.

Pensieve 同步到主分支

仅在 Pensieve 仓库本身内使用。

此技能将 experimental 或 zh 中的更改同步到 main，保留贡献者历史，并确保 main 始终作为英文发布分支。这是维护者发布流程，不是应预置到每个 Pensieve 用户项目中的默认流水线。

硬性规则

main 必须保持仅使用英文，并达到发布质量。
保留源分支的提交历史；除非用户明确要求，否则不要压缩贡献者历史。
各语言分支中的代码逻辑必须保持一致；仅文本内容可以不同。
除非下方分支规则明确要求，否则不要翻译代码标识符、路径、协议名称、命令名称、frontmatter 键或 Markdown 链接目标。
当工作区存在无关的本地更改时，不要运行破坏性的 git 清理命令。

分支策略

experimental：开发分支
zh：中文发布分支
main：英文发布分支

除非用户明确指定 experimental，否则默认源分支为 zh。默认远程仓库为 kingkongshot。

翻译范围

以下文件中的中文内容必须翻译为英文：

README.md
SKILL.md
.src/references/*.md
.src/tools/*.md
.src/templates/**/*.md

以下文件默认直接同步；仅当英文分支中存在用户可见的中文内容时才进行翻译：

脚本和代码
JSON/YAML 配置
已删除的文件
二进制资源

工作流

1. 确认范围

检查当前状态：

git branch --show-current
git status --short
git remote -v

确认源分支：

git fetch kingkongshot
git diff --stat main..kingkongshot/<source-branch>

将发生更改的文件分类为：需要翻译、直接同步、删除、二进制/配置。
如果工作区存在无关的本地更改，请在切换分支前报告这些更改。

2. 创建同步分支

从最新的 main 开始：

git checkout main
git pull kingkongshot main
git checkout -b sync/zh-to-main-<date>[-topic]

合并源分支以保留历史：

git merge kingkongshot/<source-branch> -X theirs --no-edit

如果用户明确要求仅同步少数文件，请使用定向检出：
```
git checkout kingkongshot/<source-branch> -- <file>
```
在翻译前解决冲突。

3. 翻译

规则：

将所有中文文本翻译为英文。
保留 Markdown 结构、frontmatter、代码块、命令语法和 HTML 标签。
保留有意设计的双语匹配正则表达式，例如 Exploration Reduction 兼容性检查。
英文分支文档中的安装命令必须使用 git clone -b main，而不是 git clone -b zh。
英文分支的语言切换链接应指回中文 README。
仅当脚本中的中文字符串在英文分支中对用户可见时，才进行翻译。

验证：

rg -n --pcre2 '\p{Han}' README.md SKILL.md .src docs

翻译完成后，结果中只能包含有意保留的中文内容，例如语言切换链接或双语正则表达式。

4. 验证、提交并创建 PR

运行当前仓库中已有的检查：
```
git diff --check
```

提交：

git add -A
git commit -m "translate: sync <source-branch> to main"

推送并创建 PR：

git push kingkongshot sync/zh-to-main-<date>[-topic]
gh pr create --repo kingkongshot/Pensieve --base main --head sync/zh-to-main-<date>[-topic]

除非用户明确授权执行完整的发布流程，否则在合并 PR 前请求确认。

失败时的回退处理

合并冲突仍未解决：停止操作，列出冲突文件，并直接解决冲突。优先采用源分支内容，然后进行翻译。
翻译后仍存在中文：逐项检查，将其翻译，或说明为何有意保留。
推送被拒绝：执行 fetch，将同步分支变基到最新的 kingkongshot/main，然后重试。
GitHub CLI 身份验证失败：报告确切的身份验证错误；不要切换到未知的远程仓库。

重要提示：本站仅作 Skill 资源导航与收录，正文以 GitHub 原仓库为准，版权归原项目所有。

Pensieve

Give your AI agent a continuously growing project memory.

中文 README

In one sentence: Pensieve is a self-growing CLAUDE.md that runs as a skill -- minimal context usage, compatible with all AI tools that support skills.

	CLAUDE.md / agents.md	Pensieve
Form	Single static file	Four-layer structured knowledge
Maintenance	Manual writing, manual updates	Auto-accumulation, auto-alignment
Scope	Project conventions	Conventions + decisions + facts + workflows
Linking	Flat	Semantic links forming a knowledge graph
Context usage	Full-text injection	Skill-based on-demand routing, minimal usage

Why Use Pensieve

Without	With
Have to re-explain project specs every time	Specs stored as maxims, loaded automatically
Code review standards depend on mood	Review standards solidified into executable pipelines
Repeat last week's mistake this week	Lessons auto-accumulated, skipped next time
Forget why you designed it this way three months later	Decisions record context and alternatives
Have to re-read docs to locate module boundaries every time	Knowledge caches exploration results, reuse directly

Self-Reinforcing Loop

Pensieve doesn't just store documentation -- it makes every agent conversation more precise:

Validate AI-generated plans -- "Use pensieve to check the accuracy of this plan" -> Automatically cross-references maxims and decisions; plans that violate architectural conventions are intercepted before execution
Narrow the exploration scope -- "Use pensieve to locate the entry point of the payment module" -> Knowledge contains previous exploration results, reuse directly without global search, saving tokens and time
Establish implicit connections -- "Use pensieve to analyze which workflows this refactoring will affect" -> Four-layer knowledge forms a graph through semantic links, following association chains to discover design intent and dependencies
Reduce repeated confirmations -- "Use pensieve conventions to commit code" -> Conventions and decisions are already accumulated, no more asking "what style?" or "where's the boundary?"

You don't need to manually maintain the knowledge base -- daily development feeds it automatically:

    Develop --> Commit --> Review (pipeline)
     ^                      |
     |   <-- Auto-accumulate experience <--   |
     |                      v
     +-- maxim / decision / knowledge / pipeline

During editing: After Write/Edit, the knowledge graph syncs automatically (Claude Code triggers via hooks; other clients can manually run self-improve)
During review: Executes according to project pipelines, conclusions flow back as knowledge
During retrospective: "Use pensieve to accumulate this experience" -> Insights are written to the corresponding layer

You steer the direction, Pensieve helps you avoid pitfalls.

Four-Layer Knowledge Model

Layer	Type	What It Answers	Cross-project?
MUST	maxim	What must never be violated?	Yes -- holds across projects and languages
WANT	decision	Why was this approach chosen?	No -- active trade-offs for the current project
HOW	pipeline	How should this workflow run?	Depends
IS	knowledge	What are the current facts?	No -- verifiable system facts

Layers are connected through three types of semantic links: based-on / leads-to / related. As usage accumulates, Pensieve automatically builds a directed graph of project knowledge:

See the detailed specifications under .src/references/: maxims.md, decisions.md, knowledge.md, pipelines.md.

Five Tools

Tool	What It Does	Trigger Example
`init`	Create data directory, seed default content	"Initialize pensieve for me"
`upgrade`	Refresh skill source code	"Upgrade pensieve"
`migrate`	Migrate legacy data, align seed files	"Migrate to v2"
`doctor`	Read-only scan, check structure and format	"Check if the data has any issues"
`self-improve`	Extract insights from conversations and diffs, write to four-layer knowledge	"Accumulate this experience"

Tool boundaries and redirection rules: tool-boundaries.md.

Looking for the Linus Prompt?

Pensieve was initially known for a Linus Torvalds-style guiding prompt -- using "good taste", "don't break userspace", and "paranoid about simplicity" to constrain agent behavior.

That engineering philosophy is still at the core of Pensieve, but it's no longer an isolated prompt. It's now built in as executable principles, so the agent has "good taste" from day one:

Type	Built-in Content	Effect
maxim	4 Linus-style engineering principles	Agent avoids patchy code, simplifies before extending, and preserves existing behavior
pipeline	Commit + code review + refactor	Every commit, review, and refactor checks against the standards and feeds conclusions back into knowledge
knowledge	Code-taste review standard	"Good code" becomes executable

Try it: "Use pensieve to review the code taste of recent commits" or "Use pensieve to commit local changes".

Installation

Prerequisites: git, bash, Python 3.8+.

Claude Code

# 1. Global install (one-time only)
git clone -b main https://github.com/kingkongshot/Pensieve.git ~/.claude/skills/pensieve

# 2. Install hooks (recommended; auto-syncs knowledge graph after edits, auto-checks status on session start)
bash ~/.claude/skills/pensieve/.src/scripts/install-hooks.sh

# 3. Initialize in your project
cd <your-project>
bash ~/.claude/skills/pensieve/.src/scripts/init-project-data.sh

Other Clients (Cursor / General Agents, etc.)

Replace <skill-path> with the skill directory for your client (e.g., ~/.cursor/skills/pensieve).

# 1. Global install (one-time only)
git clone -b main https://github.com/kingkongshot/Pensieve.git <skill-path>

# 2. Initialize in your project
cd <your-project>
bash <skill-path>/.src/scripts/init-project-data.sh

System code is installed globally once; user data is stored per project in <project>/.pensieve/. Multiple projects share the same system code, each maintaining independent project knowledge.

AI Agent Auto-Install Reference

When a user asks an AI agent to install Pensieve, the agent should follow this decision flow. Below, SKILL_PATH refers to the client-specific installation path (e.g., ~/.claude/skills/pensieve).

Step 1: Check global installation status

SKILL_PATH="$HOME/.claude/skills/pensieve"  # Adjust per client

if [[ -d "$SKILL_PATH/.src" ]]; then
    echo "Pensieve is already globally installed, skipping clone"
else
    SKILL_PARENT="$(dirname "$SKILL_PATH")"
    # Check if parent directory is a git repo (some users sync configs with git)
    if git -C "$SKILL_PARENT/.." rev-parse --is-inside-work-tree >/dev/null 2>&1; then
        git -C "$SKILL_PARENT/.." submodule add -b main https://github.com/kingkongshot/Pensieve.git "skills/pensieve"
    else
        git clone -b main https://github.com/kingkongshot/Pensieve.git "$SKILL_PATH"
    fi
    # Hooks are a Claude Code-specific feature; other clients skip this step
    # bash "$SKILL_PATH/.src/scripts/install-hooks.sh"
fi

Step 2: Determine whether to run project initialization

# If the current directory is the skill's parent config directory, don't auto-initialize project data
CURRENT_DIR="$(pwd)"
CONFIG_DIR="$(cd "$(dirname "$SKILL_PATH")/.." 2>/dev/null && pwd)"
if [[ "$CURRENT_DIR" == "$CONFIG_DIR" ]]; then
    echo "Current directory is the config directory, skipping project initialization. If you need to use Pensieve here, please specify explicitly."
    exit 0
fi

Step 3: Check for legacy data and initialize

HAS_LEGACY=0
for legacy_dir in .claude/skills/pensieve .agents/skills/pensieve skills/pensieve .claude/pensieve; do
    if [[ -d "$legacy_dir" ]] && [[ -d "$legacy_dir/maxims" || -d "$legacy_dir/decisions" || -d "$legacy_dir/knowledge" || -d "$legacy_dir/pipelines" ]]; then
        HAS_LEGACY=1
        break
    fi
done

if [[ "$HAS_LEGACY" -eq 1 ]]; then
    echo "Legacy Pensieve user data detected. Migrate to v2?"
    bash "$SKILL_PATH/.src/scripts/init-project-data.sh"
    bash "$SKILL_PATH/.src/scripts/run-migrate.sh"
    bash "$SKILL_PATH/.src/scripts/run-doctor.sh" --strict
elif [[ -d .pensieve ]]; then
    echo "Pensieve is already initialized in the current project"
else
    bash "$SKILL_PATH/.src/scripts/init-project-data.sh"
fi

Key takeaway: Check global install first -> Determine if parent directory is a git repo to decide clone/submodule -> Skip project initialization for config directories -> Check for legacy data to decide init/migrate.

Updating

# Update system code (one operation, all projects take effect)
cd <skill-path>
git pull --ff-only || { git fetch origin && git reset --hard "origin/$(git rev-parse --abbrev-ref HEAD)"; }

# Health check in your project (optional but recommended)
cd <your-project>
bash <skill-path>/.src/scripts/run-doctor.sh --strict

git pull --ff-only works for normal updates. If the remote branch was force-pushed (e.g., after a squash and republish), ff-only will fail, and fetch + reset will sync local to the latest remote state. This is safe -- the skill directory only contains tracked system files; user data is in <project>/.pensieve/ and won't be overwritten.

Full installation, update, reinstall, and uninstall instructions: skill-lifecycle.md.

Upgrading from Legacy Versions

If your Pensieve was installed at project level (code in <project>/.claude/skills/pensieve/), or installed via claude plugin install, you need to migrate to the v2 architecture:

# 1. Global install system code (if not already installed)
if [[ ! -d <skill-path> ]]; then
    git clone -b main https://github.com/kingkongshot/Pensieve.git <skill-path>
fi

# 2. Install hooks (Claude Code only; other clients skip this)
# bash <skill-path>/.src/scripts/install-hooks.sh

# 3. Run migration in each project
cd <your-project>
bash <skill-path>/.src/scripts/init-project-data.sh
bash <skill-path>/.src/scripts/run-migrate.sh
bash <skill-path>/.src/scripts/run-doctor.sh --strict

# 4. Uninstall old plugin (if applicable, Claude Code only)
# claude plugin uninstall pensieve 2>/dev/null || true

run-migrate.sh will automatically move user data (maxims/, decisions/, knowledge/, pipelines/) from legacy paths into <project>/.pensieve/, runtime state from <project>/.state/ into <project>/.pensieve/.state/, clean up old graph files and README copies, then delete the legacy directories.

Architecture Details

Directory Structure

~/.claude/skills/pensieve/          # User-level (single global install)
├── SKILL.md                        #   Static routing file (tracked)
├── .src/                           #   System code, templates, references, core engine
│   ├── core/
│   ├── scripts/
│   ├── templates/
│   │   ├── agents/
│   │   ├── knowledge/
│   │   ├── maxims/
│   │   └── pipelines/
│   ├── references/
│   └── tools/
└── agents/                         #   agent/UI metadata

<project>/.codex/skills/            # Project-level Codex skill (only for maintaining this repository)
└── pensieve-sync-to-main/
    ├── SKILL.md
    └── agents/
        └── openai.yaml

<project>/.pensieve/                # Project-level (per-project, can be version-controlled)
├── maxims/                         #   Engineering principles
├── decisions/                      #   Architectural decisions
├── knowledge/                      #   Cached exploration results
├── pipelines/                      #   Reusable workflows
├── state.md                        #   Dynamic: lifecycle state + knowledge graph
└── .state/                         #   Runtime artifacts (gitignored)

.src/manifest.json is the anchor for the skill root directory -- scripts locate all paths through it.

Design Principles

Physical isolation of system code and user data -- System code lives in ~/.claude/skills/pensieve/, user data in <project>/.pensieve/; git pull to update the system can never touch project data
Single source of truth for rules -- Directories, key files, and migration paths are all defined in .src/core/schema.json
Confirm before executing -- When scope is unclear, ask first; don't auto-launch long workflows
Read specs before writing data -- Before creating any user data, read the format specifications in .src/references/

Community

License

MIT

Agent Skills 是什么？

Skill 就是一个装着 SKILL.md 的文件夹：头信息写 name 和 description，正文写具体指令；Agent 平时只记描述，匹配请求后再读全文。

快速上手：装第一个 Skill

在技能库挑一条接近任务的 Skill，按详情里的安装说明放到 Agent 目录，用点名或自然语言触发一次并核对结果。

Skills 和 Prompt 怎么选？

只复制一段指令就用 Prompt；要让 Agent 按固定步骤、检查清单或脚本反复完成同一类任务，再用 Skill。

Skills 和 MCP 有什么区别？

Skill 教 Agent 一套做法；MCP 把外部数据和工具接进 Agent。很多工作流两样都要。

按任务挑 Skill，不按名字挑

先写清要完成的事，再在技能库里对 description；再看安装成本、维护状态和权限范围。