215 lines
7.4 KiB
HTML
215 lines
7.4 KiB
HTML
<!doctype html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<title>.cursor 协作指南</title>
|
||
<style>
|
||
:root {
|
||
color-scheme: dark;
|
||
--bg: #0f1117;
|
||
--panel: #171b24;
|
||
--panel-2: #1d2330;
|
||
--border: #2c3546;
|
||
--text: #e7ebf3;
|
||
--muted: #a8b0bf;
|
||
--accent: #7aa2f7;
|
||
--ok: #9ece6a;
|
||
--warn: #e0af68;
|
||
--code: #0b0e14;
|
||
--mono: "Cascadia Code", "JetBrains Mono", Consolas, monospace;
|
||
--sans: "Segoe UI", "Microsoft YaHei", sans-serif;
|
||
}
|
||
* { box-sizing: border-box; }
|
||
html { scroll-behavior: smooth; }
|
||
body {
|
||
margin: 0;
|
||
color: var(--text);
|
||
background: radial-gradient(circle at 80% 0, #18233a 0, transparent 34%), var(--bg);
|
||
font: 15px/1.7 var(--sans);
|
||
}
|
||
.layout {
|
||
width: min(1120px, calc(100% - 32px));
|
||
margin: 0 auto;
|
||
padding: 44px 0 72px;
|
||
display: grid;
|
||
grid-template-columns: 230px minmax(0, 1fr);
|
||
gap: 32px;
|
||
}
|
||
header {
|
||
grid-column: 1 / -1;
|
||
padding: 34px 38px;
|
||
border: 1px solid var(--border);
|
||
border-radius: 18px;
|
||
background: linear-gradient(135deg, var(--panel-2), var(--panel));
|
||
}
|
||
header p { max-width: 780px; margin-bottom: 0; color: var(--muted); }
|
||
h1 { margin: 0; font-size: 30px; }
|
||
h2 { margin: 0 0 16px; font-size: 21px; }
|
||
h3 { margin: 24px 0 8px; font-size: 16px; }
|
||
nav {
|
||
position: sticky;
|
||
top: 24px;
|
||
align-self: start;
|
||
padding: 18px;
|
||
border: 1px solid var(--border);
|
||
border-radius: 14px;
|
||
background: var(--panel);
|
||
}
|
||
nav strong {
|
||
display: block;
|
||
margin-bottom: 10px;
|
||
color: var(--muted);
|
||
font: 12px var(--mono);
|
||
letter-spacing: .12em;
|
||
}
|
||
nav a {
|
||
display: block;
|
||
padding: 7px 9px;
|
||
border-radius: 8px;
|
||
color: var(--muted);
|
||
text-decoration: none;
|
||
}
|
||
nav a:hover { color: var(--text); background: var(--panel-2); }
|
||
main { min-width: 0; }
|
||
section {
|
||
margin-bottom: 22px;
|
||
padding: 28px 30px;
|
||
border: 1px solid var(--border);
|
||
border-radius: 14px;
|
||
background: var(--panel);
|
||
}
|
||
ul { padding-left: 21px; }
|
||
li { margin: 6px 0; }
|
||
code {
|
||
padding: 2px 6px;
|
||
border: 1px solid var(--border);
|
||
border-radius: 6px;
|
||
color: var(--warn);
|
||
background: var(--panel-2);
|
||
font: 13px var(--mono);
|
||
}
|
||
pre {
|
||
overflow-x: auto;
|
||
padding: 15px 17px;
|
||
border: 1px solid var(--border);
|
||
border-radius: 10px;
|
||
background: var(--code);
|
||
}
|
||
pre code { padding: 0; border: 0; color: #c8d3f5; background: transparent; }
|
||
.callout {
|
||
margin: 16px 0;
|
||
padding: 12px 15px;
|
||
border-left: 3px solid var(--accent);
|
||
border-radius: 0 9px 9px 0;
|
||
color: var(--muted);
|
||
background: rgba(122, 162, 247, .08);
|
||
}
|
||
.callout.ok {
|
||
border-left-color: var(--ok);
|
||
background: rgba(158, 206, 106, .08);
|
||
}
|
||
.tag {
|
||
display: inline-block;
|
||
margin: 14px 7px 0 0;
|
||
padding: 4px 9px;
|
||
border: 1px solid var(--border);
|
||
border-radius: 999px;
|
||
color: var(--muted);
|
||
font: 12px var(--mono);
|
||
}
|
||
footer {
|
||
grid-column: 1 / -1;
|
||
text-align: center;
|
||
color: var(--muted);
|
||
font-size: 13px;
|
||
}
|
||
@media (max-width: 800px) {
|
||
.layout { grid-template-columns: 1fr; }
|
||
nav { position: static; }
|
||
header { padding: 28px; }
|
||
section { padding: 24px; }
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div class="layout">
|
||
<header>
|
||
<h1><code>.cursor</code> 协作指南</h1>
|
||
<p>项目级 Agent 记忆、计划和开发日志的基础设施。所有内容均以 <code>.cursor/</code> 为根路径；初始化后的空模板不包含任何项目历史。</p>
|
||
<span class="tag">fragment changelog</span>
|
||
<span class="tag">deterministic views</span>
|
||
<span class="tag">UTF-8 · LF</span>
|
||
</header>
|
||
|
||
<nav aria-label="目录">
|
||
<strong>目录</strong>
|
||
<a href="#structure">目录结构</a>
|
||
<a href="#changelog">开发日志</a>
|
||
<a href="#hooks">Git hooks</a>
|
||
<a href="#migration">旧格式导入</a>
|
||
<a href="#maintenance">维护约定</a>
|
||
</nav>
|
||
|
||
<main>
|
||
<section id="structure">
|
||
<h2>目录结构</h2>
|
||
<ul>
|
||
<li><code>.cursor/changelog/entries/</code>：开发日志 fragment 的唯一数据源。</li>
|
||
<li><code>.cursor/changelog/changelog-*.md</code>：由生成器确定性生成的只读视图。</li>
|
||
<li><code>.cursor/changelog/tools/</code>：生成、迁移、合并导入和 hooks 安装工具。</li>
|
||
<li><code>.cursor/deferred/registry.md</code>：延期决策登记。</li>
|
||
<li><code>.cursor/pitfalls/pitfalls.md</code>：踩坑记录。</li>
|
||
<li><code>.cursor/distillery/</code>：问题、洞察和黄金规则。</li>
|
||
<li><code>.cursor/profile/</code>：项目画像及其变更日志。</li>
|
||
<li><code>.cursor/plans/</code>：实施计划。</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<section id="changelog">
|
||
<h2>开发日志</h2>
|
||
<p>每条日志保存为 <code>.cursor/changelog/entries/<author>/<id>.md</code>。以下四个视图由生成器维护，不要手改：</p>
|
||
<ul>
|
||
<li><code>.cursor/changelog/changelog-full.md</code></li>
|
||
<li><code>.cursor/changelog/changelog-recent.md</code></li>
|
||
<li><code>.cursor/changelog/changelog-headlines.md</code></li>
|
||
<li><code>.cursor/changelog/changelog-by-author.md</code></li>
|
||
</ul>
|
||
<pre><code>python .cursor/changelog/tools/changelog_build.py
|
||
python .cursor/changelog/tools/changelog_build.py --check</code></pre>
|
||
<div class="callout">生成器要求 Python 3.10 或更高版本。</div>
|
||
</section>
|
||
|
||
<section id="hooks">
|
||
<h2>安装 Git hooks</h2>
|
||
<h3>Windows</h3>
|
||
<pre><code>powershell -ExecutionPolicy Bypass -File .cursor/changelog/tools/install-git-hooks.ps1</code></pre>
|
||
<h3>Linux / macOS</h3>
|
||
<pre><code>sh .cursor/changelog/tools/install-git-hooks.sh</code></pre>
|
||
<p><code>pre-commit</code> 会重建并暂存四个视图；<code>post-merge</code> 会在合并后重新生成视图。每个克隆只需安装一次。</p>
|
||
</section>
|
||
|
||
<section id="migration">
|
||
<h2>导入旧格式日志</h2>
|
||
<p>仅在需要把旧的聚合日志转换为 fragment 时使用：</p>
|
||
<pre><code>powershell -ExecutionPolicy Bypass -File .cursor/changelog/tools/merge-import.ps1</code></pre>
|
||
<pre><code>sh .cursor/changelog/tools/merge-import.sh</code></pre>
|
||
<p>也可将分支或 ref 作为参数传入。导入工具只添加尚不存在的 ID，随后重建并校验视图。</p>
|
||
</section>
|
||
|
||
<section id="maintenance">
|
||
<h2>维护约定</h2>
|
||
<ul>
|
||
<li>生成视图只由 <code>.cursor/changelog/tools/changelog_build.py</code> 维护。</li>
|
||
<li>新记录写入对应模板文件，不在模板中保留其他项目的数据。</li>
|
||
<li>所有文本文件使用 UTF-8（无 BOM）和 LF 换行。</li>
|
||
</ul>
|
||
<div class="callout ok">本页与 <code>.cursor/README.md</code> 语义一致。</div>
|
||
</section>
|
||
</main>
|
||
|
||
<footer>干净基础骨架 · 无项目历史</footer>
|
||
</div>
|
||
</body>
|
||
</html>
|