decodie-overview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Decodie — Overview Mode

Decodie — 概览模式

Generate a high-level overview of a file, directory, or project — answering "what is this and how is it organized" rather than line-by-line explanations. Produces a single summary entry per target, intended as an onboarding starting point.

This mode persists by default — overviews are saved as learning entries. Re-running on the same target overwrites the existing overview rather than accumulating versions.

This mode is read-only with respect to source code. You only read source files and write to the

.decodie/

directory.

生成文件、目录或项目的高级概览——重点回答“这是什么以及它的组织结构是怎样的”，而非逐行解释。每个目标生成单个摘要条目，作为入门的起点。

此模式默认会持久化存储——概览会保存为学习条目。对同一目标重新运行会覆盖现有概览，而非累积版本。

此模式对源代码是只读的。你仅会读取源文件，并写入到

.decodie/

目录中。

Activation and Argument Parsing

激活与参数解析

Extract the target path. If none provided, use the project root.
Validate the target. Confirm it exists and is a file or directory.
Determine target scope:
- File —
```
entry_points
```
  and
```
dependencies
```
  may be omitted.
- Directory —
```
entry_points
```
  and
```
dependencies
```
  are usually meaningful.
- Project root — all four overview fields apply.
Canonicalize the target path for regeneration lookup:
- File: relative path (e.g.,
```
src/utils/helpers.ts
```
  )
- Directory or project root: relative path with trailing slash (e.g.,
```
src/auth/
```
  ,
```
./
```
  )

提取目标路径。如果未提供，则使用项目根目录。
验证目标。确认目标存在且为文件或目录。
确定目标范围：
- 文件 — 可省略
```
entry_points
```
  和
```
dependencies
```
  。
- 目录 —
```
entry_points
```
  和
```
dependencies
```
  通常有意义。
- 项目根目录 — 四个概览字段均适用。
规范化目标路径以便重新生成时查找：
- 文件：相对路径（例如：
```
src/utils/helpers.ts
```
  ）
- 目录或项目根目录：带尾部斜杠的相对路径（例如：
```
src/auth/
```
  ,
```
./
```
  ）

Setup

设置步骤

Check if

.decodie/

exists at the project root. If not, create it:

.decodie/index.json

with

{ "version": "1.0", "project": "<directory-name>", "entries": [] }

```
.decodie/config.json
```
with default preferences
```
.decodie/sessions/
```
directory

Load the index summary. Run:

bash

bash scripts/summarize-index.sh "$(pwd)"

If unavailable, read

.decodie/index.json

directly.

Determine session ID. Find the highest
```
NNN
```
for today in
```
.decodie/sessions/
```
matching
```
overview-YYYY-MM-DD-NNN
```
, then increment.

检查项目根目录下是否存在

.decodie/

。如果不存在，则创建：

.decodie/index.json

，内容为

{ "version": "1.0", "project": "<directory-name>", "entries": [] }

```
.decodie/config.json
```
，包含默认偏好设置
```
.decodie/sessions/
```
目录

加载索引摘要。运行：
bash
```
bash scripts/summarize-index.sh "$(pwd)"
```
如果不可用，则直接读取
```
.decodie/index.json
```
。
确定会话ID。在
```
.decodie/sessions/
```
中找到今日最高的
```
NNN
```
，匹配格式
```
overview-YYYY-MM-DD-NNN
```
，然后递增。

Regeneration vs Fresh Entry

重新生成 vs 全新条目

Before generating, check for an existing overview:

Read
```
.decodie/index.json
```
.

Find any entry where

decision_type === "overview"

and

sources

[<canonicalized-target-path>]

If found (regeneration): reuse the existing
```
id
```
, generate fresh content, update the index entry in place. The previous session file is left on disk but no longer referenced.
If not found: generate a new entry with a fresh ID.

生成前，检查是否存在现有概览：

读取
```
.decodie/index.json
```
。

查找任何满足

decision_type === "overview"

且

sources

为

[<规范化目标路径>]

的条目。

如果找到（重新生成）：复用现有
```
id
```
，生成新内容，就地更新索引条目。之前的会话文件会保留在磁盘上，但不再被引用。
如果未找到：生成带有新ID的全新条目。

Generation Process

生成流程

Read the target:
- File: read in full.
- Directory: list top-level entries, read structural files (
```
package.json
```
  ,
```
composer.json
```
  ,
```
pyproject.toml
```
  ,
```
README.md
```
  , etc.), sample representative source files.
- Project root: additionally inspect entry-point manifests and dependency manifests.
Identify four overview dimensions:
- purpose
  (required) — 2-4 sentences describing what this code is for. Lead with intent, not implementation.
- structure
  (required) — how the code is organized (sections, modules, key directories and their roles).
- entry_points
  (optional) — callable surfaces: exported functions, CLI commands, HTTP routes, framework hooks. Omit if not meaningful.
- dependencies
  (optional) — notable internal or external dependencies and what they provide. Omit trivia.
Write in plain prose. Avoid jargon-heavy bullet lists; the goal is human onboarding. Calibrate length to scope.

读取目标：
- 文件：完整读取。
- 目录：列出顶层条目，读取结构文件（
```
package.json
```
  ,
```
composer.json
```
  ,
```
pyproject.toml
```
  ,
```
README.md
```
  等），以及代表性的示例源文件。
- 项目根目录：额外检查入口点清单和依赖项清单。
识别四个概览维度：
- purpose
  （必填）——2-4句话描述此代码的用途。重点说明意图，而非实现细节。
- structure
  （必填）——代码的组织方式（章节、模块、关键目录及其作用）。
- entry_points
  （可选）——可调用的接口：导出函数、CLI命令、HTTP路由、框架钩子。如果无意义则省略。
- dependencies
  （可选）——重要的内部或外部依赖项及其提供的功能。忽略无关紧要的依赖。
使用平实的散文风格撰写。避免充满术语的项目符号列表；目标是帮助用户快速入门。根据范围调整内容长度。

Entry Generation

条目生成

Index entry metadata

索引条目元数据

id
: Reuse existing for regeneration; generate fresh otherwise. Format:
```
entry-{unix-timestamp}-{random-4-hex-chars}
```
title
: e.g., "Overview:
```
src/auth/
```
— token issuance and verification"
experience_level
:
```
"foundational"
```
(overviews are onboarding entry points).
decision_type
:
```
"overview"
```
topics
: Lowercase kebab-case tags. Reuse existing tags.
lifecycle
:
```
"active"
```
sources
: Array with exactly one entry — the canonicalized target path.
references
: For single-file overviews, one reference to the file. For directory/project, empty array.

content_file
: relative path to session file, e.g.

sessions/overview-2026-03-27-001.json

id
：重新生成时复用现有ID；否则生成新ID。格式：
```
entry-{unix-timestamp}-{random-4-hex-chars}
```
title
：例如："概览：
```
src/auth/
```
— 令牌签发与验证"
experience_level
：
```
"foundational"
```
（概览是入门起点）
decision_type
：
```
"overview"
```
topics
：小写短横线分隔的标签。复用现有标签。
lifecycle
：
```
"active"
```
sources
：仅包含一个条目的数组——规范化后的目标路径。
references
：单文件概览时，包含一个指向该文件的引用；目录/项目概览时，为空数组。

content_file
：会话文件的相对路径，例如

sessions/overview-2026-03-27-001.json

Session entry content (overview shape)

会话条目内容（概览结构）

Use the overview shape — different from standard entries:

decision_type
:
```
"overview"
```
purpose
(required) — what the target code is for
structure
(required) — how the target is organized
entry_points
(optional) — callable surfaces
dependencies
(optional) — notable dependencies

使用概览结构——与标准条目不同：

decision_type
：
```
"overview"
```
purpose
（必填）——目标代码的用途
structure
（必填）——目标的组织方式
entry_points
（可选）——可调用接口
dependencies
（可选）——重要依赖项

Session Closure

会话结束

Set
```
timestamp_end
```
.
Write a
```
summary
```
noting the target and whether this was fresh or regenerated.
Confirm:
- Fresh: "Generated overview for
```
<target>
```
  as entry
```
<id>
```
  in session
```
<session_id>
```
  ."
- Regeneration: "Regenerated overview for
```
<target>
```
  (entry
```
<id>
```
  )."

设置
```
timestamp_end
```
。
写入
```
summary
```
，注明目标以及此次是全新生成还是重新生成。
确认内容：
- 全新生成："为
```
<target>
```
  生成概览，作为会话
```
<session_id>
```
  中的条目
```
<id>
```
  。"
- 重新生成："重新生成
```
<target>
```
  的概览（条目
```
<id>
```
  ）。"

Data Format

数据格式

See references/schema.md for the full

.decodie/

data format.

完整的

.decodie/

数据格式请参见references/schema.md。

Important Notes

重要说明

Always-latest, not append-only. Re-running overwrites the index entry.
One entry per target. Do not fan out to per-file entries — that is analyze mode's job.
Be honest about uncertainty. If the target's purpose is ambiguous, say so.
Language-agnostic. Adapt to whatever language and framework the project uses.
Self-contained data. The
```
.decodie/
```
directory can be removed without affecting the project.

始终保留最新版本，而非追加式存储。重新运行会覆盖索引条目。
每个目标对应一个条目。不要拆分为单个文件条目——这是分析模式的工作。
如实说明不确定的内容。如果目标的用途不明确，请直接说明。
语言无关。适配项目所使用的任何语言和框架。
数据独立。删除
```
.decodie/
```
目录不会影响项目本身。