@devport-kr/portki 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +11 -0
- package/AGENTS.md +205 -0
- package/CLAUDE.md +174 -0
- package/README.md +144 -0
- package/dist/cli.cjs +6 -0
- package/dist/cli.js +4465 -0
- package/package.json +60 -0
package/.env.example
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Optional overrides only.
|
|
2
|
+
# The public branch works without any .env file.
|
|
3
|
+
|
|
4
|
+
# Quality gate: standard | strict
|
|
5
|
+
DEVPORT_QUALITY_GATE_LEVEL=strict
|
|
6
|
+
|
|
7
|
+
# Trend ingestion window in days
|
|
8
|
+
DEVPORT_TREND_WINDOW_DAYS=180
|
|
9
|
+
|
|
10
|
+
# Official docs discovery mode
|
|
11
|
+
DEVPORT_OFFICIAL_DOC_DISCOVERY=auto
|
package/AGENTS.md
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# portki public-agent instructions
|
|
2
|
+
|
|
3
|
+
## Role
|
|
4
|
+
|
|
5
|
+
You are the AI agent operating this tool. This repository is the public branch of the devport wiki generator. It reads public GitHub repositories and produces Korean wiki content as plain Markdown files. `src/agent.ts` handles the deterministic pipeline only. The agent is responsible for understanding the codebase and writing the content.
|
|
6
|
+
|
|
7
|
+
Do not call external LLM APIs. Do not add OpenAI or Anthropic API usage.
|
|
8
|
+
|
|
9
|
+
## Public Branch Rules
|
|
10
|
+
|
|
11
|
+
- This branch is the public version.
|
|
12
|
+
- There is no DB, no embeddings, no PostgreSQL, and no OpenAI API dependency.
|
|
13
|
+
- It should work without `.env` setup.
|
|
14
|
+
- Final output lives under `devport-output/wiki/{owner}/{repo}/` as Markdown files.
|
|
15
|
+
- `persist-section` means local validation plus session registration only.
|
|
16
|
+
- `finalize` assembles the full Markdown wiki bundle.
|
|
17
|
+
- `package` is the monolithic path that exports Markdown directly from a full accepted output.
|
|
18
|
+
|
|
19
|
+
## Only Use `src/agent.ts`
|
|
20
|
+
|
|
21
|
+
The only supported commands are:
|
|
22
|
+
|
|
23
|
+
- `ingest`
|
|
24
|
+
- `detect`
|
|
25
|
+
- `package`
|
|
26
|
+
- `plan-sections`
|
|
27
|
+
- `validate-plan`
|
|
28
|
+
- `persist-section`
|
|
29
|
+
- `finalize`
|
|
30
|
+
|
|
31
|
+
Do not use legacy entrypoints.
|
|
32
|
+
|
|
33
|
+
## Required End-to-End Flow
|
|
34
|
+
|
|
35
|
+
Preferred chunked flow:
|
|
36
|
+
|
|
37
|
+
1. `ingest`
|
|
38
|
+
2. `plan-sections`
|
|
39
|
+
3. The agent writes `section-plan.json`
|
|
40
|
+
4. `validate-plan`
|
|
41
|
+
5. The agent writes section outputs
|
|
42
|
+
6. `persist-section` for each section
|
|
43
|
+
7. `finalize --advance_baseline`
|
|
44
|
+
|
|
45
|
+
Monolithic alternative for small repos:
|
|
46
|
+
|
|
47
|
+
1. `ingest`
|
|
48
|
+
2. The agent writes `accepted-output.json`
|
|
49
|
+
3. `package --advance_baseline`
|
|
50
|
+
|
|
51
|
+
## Public Repo Assumption
|
|
52
|
+
|
|
53
|
+
- This branch targets public repositories by default.
|
|
54
|
+
- `GITHUB_TOKEN` is not required.
|
|
55
|
+
- Private repository support is out of scope for this branch.
|
|
56
|
+
|
|
57
|
+
## Workspace Naming Rule
|
|
58
|
+
|
|
59
|
+
If multiple repos are processed in parallel, all agent-authored intermediate files must be stored in `devport-output/workspace/` and prefixed with the repo slug.
|
|
60
|
+
|
|
61
|
+
Examples:
|
|
62
|
+
|
|
63
|
+
- `devport-output/workspace/ollama-artifact.json`
|
|
64
|
+
- `devport-output/workspace/ollama-section-plan.json`
|
|
65
|
+
- `devport-output/workspace/ollama-section-1-output.json`
|
|
66
|
+
|
|
67
|
+
## Commands
|
|
68
|
+
|
|
69
|
+
### `ingest`
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The agent must read these fields:
|
|
76
|
+
|
|
77
|
+
- `ingest_run_id`
|
|
78
|
+
- `commit_sha`
|
|
79
|
+
- `repo_ref`
|
|
80
|
+
- `snapshot_path`
|
|
81
|
+
- `files_scanned`
|
|
82
|
+
- `metadata.key_paths`
|
|
83
|
+
- `metadata.language_mix`
|
|
84
|
+
|
|
85
|
+
### `detect`
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
npx tsx src/agent.ts detect --repo owner/repo
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Interpret the status as:
|
|
92
|
+
|
|
93
|
+
- `noop`: do nothing
|
|
94
|
+
- `incremental`: regenerate only `impacted_section_ids`
|
|
95
|
+
- `full-rebuild`: regenerate everything
|
|
96
|
+
|
|
97
|
+
### `plan-sections`
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
npx tsx src/agent.ts plan-sections --artifact devport-output/workspace/{repo-slug}-artifact.json --out devport-output/workspace/{repo-slug}-plan-context.json
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
The output includes:
|
|
104
|
+
|
|
105
|
+
- `profile`
|
|
106
|
+
- `readmeExcerpt`
|
|
107
|
+
- `keyPaths`
|
|
108
|
+
- `fileTree`
|
|
109
|
+
- `constraints`
|
|
110
|
+
|
|
111
|
+
### `validate-plan`
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
npx tsx src/agent.ts validate-plan --input devport-output/workspace/{repo-slug}-section-plan.json --context devport-output/workspace/{repo-slug}-plan-context.json --out devport-output/workspace/{repo-slug}-section-plan.json
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### `persist-section`
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
npx tsx src/agent.ts persist-section --plan devport-output/workspace/{repo-slug}-section-plan.json --section sec-1 --input devport-output/workspace/{repo-slug}-section-1-output.json
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
This command only does the following:
|
|
124
|
+
|
|
125
|
+
- validates the section JSON schema
|
|
126
|
+
- checks body length, repetition, Mermaid, and source paths
|
|
127
|
+
- updates `session.json`
|
|
128
|
+
|
|
129
|
+
It does not write to a database, generate embeddings, or call external APIs.
|
|
130
|
+
|
|
131
|
+
### `finalize`
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
npx tsx src/agent.ts finalize --plan devport-output/workspace/{repo-slug}-section-plan.json --advance_baseline
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
This command:
|
|
138
|
+
|
|
139
|
+
- validates cross-section repetition
|
|
140
|
+
- assembles persisted sections from the local session
|
|
141
|
+
- writes `devport-output/wiki/{owner}/{repo}/README.md`
|
|
142
|
+
- writes section Markdown files such as `devport-output/wiki/{owner}/{repo}/01-sec-1.md`
|
|
143
|
+
- optionally advances the freshness baseline
|
|
144
|
+
|
|
145
|
+
### `package`
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
npx tsx src/agent.ts package --input devport-output/workspace/{repo-slug}-accepted-output.json --advance_baseline
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
This validates a monolithic accepted output and writes the same Markdown wiki bundle.
|
|
152
|
+
|
|
153
|
+
## Section Writing Rules
|
|
154
|
+
|
|
155
|
+
- Read actual files from the snapshot.
|
|
156
|
+
- All Korean prose must use formal `합니다` style.
|
|
157
|
+
- Prefer 4 to 6 sections.
|
|
158
|
+
- Each section must have at least 3 subsections.
|
|
159
|
+
- Each `bodyKo` must be at least 3,000 characters.
|
|
160
|
+
- At least one architecture Mermaid block must exist.
|
|
161
|
+
- `sourcePaths` must point to real files in the snapshot.
|
|
162
|
+
- Do not pad with repeated sentences or repeated long blocks.
|
|
163
|
+
|
|
164
|
+
## `sub-1-1` Override
|
|
165
|
+
|
|
166
|
+
`sub-1-1` is the project-level introduction.
|
|
167
|
+
|
|
168
|
+
- Explain what the project is and why it exists.
|
|
169
|
+
- Include installation or getting-started guidance.
|
|
170
|
+
- Briefly map what the remaining sections cover.
|
|
171
|
+
- Do not make it a code call-flow analysis section.
|
|
172
|
+
|
|
173
|
+
## Output Shape
|
|
174
|
+
|
|
175
|
+
Per-section output:
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{
|
|
179
|
+
"sectionId": "sec-1",
|
|
180
|
+
"titleKo": "Project Overview",
|
|
181
|
+
"summaryKo": "This section explains ...",
|
|
182
|
+
"sourcePaths": ["README.md", "src/main.ts"],
|
|
183
|
+
"subsections": [
|
|
184
|
+
{
|
|
185
|
+
"sectionId": "sec-1",
|
|
186
|
+
"subsectionId": "sub-1-1",
|
|
187
|
+
"titleKo": "Project Introduction and Overview",
|
|
188
|
+
"bodyKo": "..."
|
|
189
|
+
}
|
|
190
|
+
]
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The final result is Markdown, not a delivery JSON artifact.
|
|
195
|
+
|
|
196
|
+
## Output Paths
|
|
197
|
+
|
|
198
|
+
```text
|
|
199
|
+
devport-output/
|
|
200
|
+
workspace/
|
|
201
|
+
snapshots/{owner}/{repo}/
|
|
202
|
+
chunked/{owner}/{repo}/session.json
|
|
203
|
+
wiki/{owner}/{repo}/
|
|
204
|
+
freshness/state.json
|
|
205
|
+
```
|
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# portki public-agent instructions for Claude Code
|
|
2
|
+
|
|
3
|
+
## Role
|
|
4
|
+
|
|
5
|
+
You are the AI agent operating this tool. This repository is the public branch of the devport wiki generator. It reads public GitHub repositories and produces Korean wiki content as plain Markdown files. `src/agent.ts` handles the deterministic pipeline only. The agent is responsible for understanding the codebase and writing the content.
|
|
6
|
+
|
|
7
|
+
Do not call external LLM APIs. Do not add OpenAI or Anthropic API usage.
|
|
8
|
+
|
|
9
|
+
## Public Branch Rules
|
|
10
|
+
|
|
11
|
+
- This branch is the public version.
|
|
12
|
+
- There is no DB, no embeddings, no PostgreSQL, and no OpenAI API dependency.
|
|
13
|
+
- It should work without `.env` setup.
|
|
14
|
+
- Final output lives under `devport-output/wiki/{owner}/{repo}/` as Markdown files.
|
|
15
|
+
- `persist-section` means local validation plus session registration only.
|
|
16
|
+
- `finalize` assembles the full Markdown wiki bundle.
|
|
17
|
+
- `package` is the monolithic path that exports Markdown directly from a full accepted output.
|
|
18
|
+
|
|
19
|
+
## Only Use `src/agent.ts`
|
|
20
|
+
|
|
21
|
+
The only supported commands are:
|
|
22
|
+
|
|
23
|
+
- `ingest`
|
|
24
|
+
- `detect`
|
|
25
|
+
- `package`
|
|
26
|
+
- `plan-sections`
|
|
27
|
+
- `validate-plan`
|
|
28
|
+
- `persist-section`
|
|
29
|
+
- `finalize`
|
|
30
|
+
|
|
31
|
+
## Required Flow
|
|
32
|
+
|
|
33
|
+
Preferred chunked flow:
|
|
34
|
+
|
|
35
|
+
1. `ingest`
|
|
36
|
+
2. `plan-sections`
|
|
37
|
+
3. The agent writes `section-plan.json`
|
|
38
|
+
4. `validate-plan`
|
|
39
|
+
5. The agent writes section outputs
|
|
40
|
+
6. `persist-section` for each section
|
|
41
|
+
7. `finalize --advance_baseline`
|
|
42
|
+
|
|
43
|
+
Monolithic alternative for small repos:
|
|
44
|
+
|
|
45
|
+
1. `ingest`
|
|
46
|
+
2. The agent writes `accepted-output.json`
|
|
47
|
+
3. `package --advance_baseline`
|
|
48
|
+
|
|
49
|
+
## Public Repo Assumption
|
|
50
|
+
|
|
51
|
+
- This branch targets public repositories by default.
|
|
52
|
+
- `GITHUB_TOKEN` is not required.
|
|
53
|
+
- Private repository support is out of scope for this branch.
|
|
54
|
+
|
|
55
|
+
## Workspace Naming Rule
|
|
56
|
+
|
|
57
|
+
All agent-authored intermediate files must be written to `devport-output/workspace/` and prefixed with the repo slug.
|
|
58
|
+
|
|
59
|
+
Examples:
|
|
60
|
+
|
|
61
|
+
- `devport-output/workspace/redis-artifact.json`
|
|
62
|
+
- `devport-output/workspace/redis-section-plan.json`
|
|
63
|
+
- `devport-output/workspace/redis-section-2-output.json`
|
|
64
|
+
|
|
65
|
+
## Commands
|
|
66
|
+
|
|
67
|
+
### `ingest`
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Read these fields from the artifact:
|
|
74
|
+
|
|
75
|
+
- `ingest_run_id`
|
|
76
|
+
- `commit_sha`
|
|
77
|
+
- `repo_ref`
|
|
78
|
+
- `snapshot_path`
|
|
79
|
+
- `files_scanned`
|
|
80
|
+
- `metadata.key_paths`
|
|
81
|
+
- `metadata.language_mix`
|
|
82
|
+
|
|
83
|
+
### `detect`
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
npx tsx src/agent.ts detect --repo owner/repo
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- `noop`: stop
|
|
90
|
+
- `incremental`: regenerate only the impacted sections
|
|
91
|
+
- `full-rebuild`: regenerate everything
|
|
92
|
+
|
|
93
|
+
### `plan-sections`
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
npx tsx src/agent.ts plan-sections --artifact devport-output/workspace/{repo-slug}-artifact.json --out devport-output/workspace/{repo-slug}-plan-context.json
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### `validate-plan`
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npx tsx src/agent.ts validate-plan --input devport-output/workspace/{repo-slug}-section-plan.json --context devport-output/workspace/{repo-slug}-plan-context.json --out devport-output/workspace/{repo-slug}-section-plan.json
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### `persist-section`
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
npx tsx src/agent.ts persist-section --plan devport-output/workspace/{repo-slug}-section-plan.json --section sec-1 --input devport-output/workspace/{repo-slug}-section-1-output.json
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
What it does:
|
|
112
|
+
|
|
113
|
+
- validates the section JSON
|
|
114
|
+
- checks body length, repetition, Mermaid, and source paths
|
|
115
|
+
- updates the local `session.json`
|
|
116
|
+
|
|
117
|
+
What it does not do:
|
|
118
|
+
|
|
119
|
+
- database writes
|
|
120
|
+
- embedding generation
|
|
121
|
+
- external API calls
|
|
122
|
+
|
|
123
|
+
### `finalize`
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npx tsx src/agent.ts finalize --plan devport-output/workspace/{repo-slug}-section-plan.json --advance_baseline
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Outputs:
|
|
130
|
+
|
|
131
|
+
- `devport-output/wiki/{owner}/{repo}/README.md`
|
|
132
|
+
- `devport-output/wiki/{owner}/{repo}/01-sec-1.md`
|
|
133
|
+
- additional section Markdown files
|
|
134
|
+
|
|
135
|
+
### `package`
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
npx tsx src/agent.ts package --input devport-output/workspace/{repo-slug}-accepted-output.json --advance_baseline
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
This validates a monolithic accepted output and writes the same Markdown result.
|
|
142
|
+
|
|
143
|
+
## Writing Rules
|
|
144
|
+
|
|
145
|
+
- Use real snapshot files only.
|
|
146
|
+
- All Korean prose must use formal `합니다` style.
|
|
147
|
+
- Prefer 4 to 6 sections.
|
|
148
|
+
- Each section must have at least 3 subsections.
|
|
149
|
+
- Each `bodyKo` must be at least 3,000 characters.
|
|
150
|
+
- Include at least one Mermaid architecture block.
|
|
151
|
+
- `sourcePaths` must be real snapshot paths.
|
|
152
|
+
- Do not use repetitive filler blocks.
|
|
153
|
+
|
|
154
|
+
## `sub-1-1` Override
|
|
155
|
+
|
|
156
|
+
`sub-1-1` is the project introduction summary.
|
|
157
|
+
|
|
158
|
+
- explain the project purpose
|
|
159
|
+
- explain the problem space
|
|
160
|
+
- include getting-started guidance
|
|
161
|
+
- briefly map the remaining sections
|
|
162
|
+
|
|
163
|
+
Code call-flow analysis should begin in `sub-1-2` or later.
|
|
164
|
+
|
|
165
|
+
## Output Paths
|
|
166
|
+
|
|
167
|
+
```text
|
|
168
|
+
devport-output/
|
|
169
|
+
workspace/
|
|
170
|
+
snapshots/{owner}/{repo}/
|
|
171
|
+
chunked/{owner}/{repo}/session.json
|
|
172
|
+
wiki/{owner}/{repo}/
|
|
173
|
+
freshness/state.json
|
|
174
|
+
```
|
package/README.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# portki (포트키)
|
|
2
|
+
|
|
3
|
+
**portki**는 **ports** + **wiki** 의 합성어로 ['포트키(Portkey)'](https://en.wikipedia.org/wiki/Magical_objects_in_Harry_Potter#Portkeys)처럼 순간이동해 다양한 AI 프로젝트를 만날 수 있는 Agent 입니다. [devport](https://devport.kr)의 [ports](https://devport.kr/ports)에 있는 모든 위키를 책임지고 있습니다.
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
## 주요 기능
|
|
7
|
+
|
|
8
|
+
- **GitHub 저장소 스냅샷 수집**: 저장소의 코드를 분석하기 위해 특정 커밋 시점의 스냅샷을 다운로드합니다.
|
|
9
|
+
- **AI 에이전트 인터페이스**: AI가 코드베이스를 직접 읽고, 분석하여 위키 문서를 작성할 수 있도록 기계적인 파이프라인(스냅샷, 변경 감지, 검증, 세션 기록, Markdown 출력 등)을 제공합니다.
|
|
10
|
+
- **청크 기반 생성 (Chunked Generation)**: 저장소의 규모가 클 경우, 문서를 여러 섹션으로 나누고 각 섹션 단위로 상세한 문서를 생성 및 검증한 뒤 로컬 세션 상태에 반영합니다.
|
|
11
|
+
- **순수 Markdown 출력**: 최종 위키를 데이터베이스가 아니라 `README.md`와 섹션별 `.md` 파일로 출력합니다.
|
|
12
|
+
- **증분 업데이트 (Incremental Update)**: 전체 코드를 매번 다시 분석하지 않고, 마지막 위키 생성 커밋 이후 변경된 파일과 영향을 받는 섹션만 추적하여 위키를 효율적으로 갱신합니다.
|
|
13
|
+
|
|
14
|
+
## 설치
|
|
15
|
+
|
|
16
|
+
Node.js 환경이 필요합니다.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
공개 버전에서는 `.env`를 만들 필요가 없습니다.
|
|
23
|
+
|
|
24
|
+
출시 후에는 로컬 clone 없이도 사용할 수 있습니다.
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npx @devport-kr/portki help
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
또는 전역 설치:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npm install -g @devport-kr/portki
|
|
34
|
+
portki help
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## GitHub Releases
|
|
38
|
+
|
|
39
|
+
`public` 브랜치에서는 GitHub Release를 만들 수 있습니다.
|
|
40
|
+
|
|
41
|
+
- `v*` 태그를 `public` 브랜치 커밋에 push하면 Release가 자동으로 생성됩니다.
|
|
42
|
+
- Actions의 수동 실행(`workflow_dispatch`)으로도 Release를 만들 수 있습니다.
|
|
43
|
+
- Release에는 자동 생성된 노트와 함께 소스 아카이브(`.tar.gz`, `.zip`), npm 패키지 tarball(`devport-kr-portki-<version>.tgz`), SHA256 체크섬 파일이 첨부됩니다.
|
|
44
|
+
- npm publish workflow를 함께 켜두면 같은 `v*` 태그에서 npm 패키지도 배포할 수 있습니다.
|
|
45
|
+
|
|
46
|
+
기본 절차:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
git checkout public
|
|
50
|
+
git pull origin public
|
|
51
|
+
|
|
52
|
+
# package.json version과 태그는 일치해야 합니다.
|
|
53
|
+
git tag v0.1.1
|
|
54
|
+
git push origin public --follow-tags
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
npm 배포까지 하려면 저장소 Secrets에 `NPM_TOKEN`을 추가해야 합니다.
|
|
58
|
+
|
|
59
|
+
## 권장 실행 환경
|
|
60
|
+
**(2026년 3월 7일 기준)**
|
|
61
|
+
| 환경 | 권장 모델 | (Effort (Thinking) Level) | 설정 지침 |
|
|
62
|
+
|------|-----------|--------------------------|------------------|
|
|
63
|
+
| **Claude Code** | `Opus 4.6` | High | [`CLAUDE.md`](./CLAUDE.md)|
|
|
64
|
+
| **Codex** | `GPT-5.4` | xHigh | [`AGENTS.md`](./AGENTS.md)|
|
|
65
|
+
| **Gemini CLI** | `gemini 3.1-pro-preview` | High | [`AGENTS.md`](./AGENTS.md)|
|
|
66
|
+
|
|
67
|
+
## 명령어 (Commands)
|
|
68
|
+
|
|
69
|
+
모든 명령은 프로젝트 루트에서 실행합니다.
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
npx tsx src/agent.ts <command> [flags]
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
| 명령 | 설명 |
|
|
76
|
+
|------|------|
|
|
77
|
+
| `ingest` | 저장소 스냅샷을 수집하고 분석용 메타데이터(`artifact.json`)를 생성합니다. |
|
|
78
|
+
| `plan-sections` | 저장소 구조를 분석하여 섹션별 작성 계획을 위한 컨텍스트와 중점 분석 대상 파일 목록을 제공합니다. |
|
|
79
|
+
| `validate-plan` | AI가 생성한 섹션 플랜의 정합성(스키마, 조건 등)을 검증합니다. |
|
|
80
|
+
| `persist-section` | 생성된 단일 섹션의 품질을 검증하고, 허용되면 로컬 세션 상태에 반영합니다. |
|
|
81
|
+
| `finalize` | 작성 완료된 모든 섹션 간의 교차 검증을 수행하고, 최종 Markdown 위키와 기준점을 업데이트합니다. |
|
|
82
|
+
| `package` | 위키 결과물 규격을 검증하고 순수 Markdown 위키 번들로 출력합니다. |
|
|
83
|
+
| `detect` | 마지막 배포 시점과 현재 저장소의 변경 사항을 비교하여 증분 업데이트 필요 여부와 대상 섹션을 파악합니다. |
|
|
84
|
+
|
|
85
|
+
## 워크플로우
|
|
86
|
+
|
|
87
|
+
이 도구는 AI 에이전트가 위키 문서를 더 정확하고 꼼꼼하게 작성하도록 **청크 단위 작업**을 권장합니다.
|
|
88
|
+
|
|
89
|
+
### 1. 청크 단위 위키 생성 (권장)
|
|
90
|
+
|
|
91
|
+
저장소를 분석하여 여러 섹션으로 분리한 후 각 섹션별로 코드를 깊이 있게 확인하고 작성하는 방식입니다.
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# 1. 저장소 스냅샷 수집
|
|
95
|
+
npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
|
|
96
|
+
|
|
97
|
+
# 2. 분석 및 섹션 계획 수립 준비 (컨텍스트 생성)
|
|
98
|
+
npx tsx src/agent.ts plan-sections --artifact devport-output/workspace/{repo-slug}-artifact.json --out devport-output/workspace/{repo-slug}-plan-context.json
|
|
99
|
+
|
|
100
|
+
# (AI 작업: plan-context.json과 주요 코드를 바탕으로 {repo-slug}-section-plan.json 생성)
|
|
101
|
+
|
|
102
|
+
# 3. 플랜 검증
|
|
103
|
+
npx tsx src/agent.ts validate-plan --input devport-output/workspace/{repo-slug}-section-plan.json --context devport-output/workspace/{repo-slug}-plan-context.json --out devport-output/workspace/{repo-slug}-section-plan.json
|
|
104
|
+
|
|
105
|
+
# 4. 각 섹션별 작성 및 세션 반영 (전체 섹션 완료 시까지 반복)
|
|
106
|
+
# (AI 작업: 해당 섹션의 코드를 분석하고 {repo-slug}-section-1-output.json 생성)
|
|
107
|
+
npx tsx src/agent.ts persist-section --plan devport-output/workspace/{repo-slug}-section-plan.json --section sec-1 --input devport-output/workspace/{repo-slug}-section-1-output.json
|
|
108
|
+
|
|
109
|
+
# 5. 최종 완성 및 증분 베이스라인 갱신
|
|
110
|
+
npx tsx src/agent.ts finalize --plan devport-output/workspace/{repo-slug}-section-plan.json --advance_baseline
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`finalize`가 완료되면 `devport-output/wiki/{owner}/{repo}/README.md`와 섹션별 Markdown 파일이 생성됩니다.
|
|
114
|
+
|
|
115
|
+
### 2. 증분 업데이트 (Incremental Update)
|
|
116
|
+
|
|
117
|
+
이전에 작성 완료된 위키를 바탕으로 변경된 파일들만 식별하여 최신화합니다.
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
# 1. 변경사항 감지
|
|
121
|
+
npx tsx src/agent.ts detect --repo owner/repo
|
|
122
|
+
# 반환된 JSON의 status에 따라 분기:
|
|
123
|
+
# - noop: 변경점 없음 (수정 불필요)
|
|
124
|
+
# - incremental: 변경된 코드와 영향을 받는 섹션(impacted_section_ids)만 재생성
|
|
125
|
+
# - full-rebuild: 너무 많은 변화로 인해 전체 위키 재작성 필요
|
|
126
|
+
|
|
127
|
+
# 2. 재생성 필요 시 최신 코드로 스냅샷 다시 수집
|
|
128
|
+
npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
|
|
129
|
+
|
|
130
|
+
# (이후 영향을 받는 섹션만 다시 작성하여 persist-section 후 finalize 수행)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## 출력 경로 (File Layout)
|
|
134
|
+
|
|
135
|
+
작업 중에 AI가 생성한 임시 파일과 파이프라인이 생성한 모든 데이터는 프로젝트 루트를 오염시키지 않도록 `devport-output/` 내부에 기록됩니다. (이 디렉터리는 `.gitignore`에 포함되어 있습니다.)
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
devport-output/
|
|
139
|
+
workspace/ # AI 에이전트가 중간에 생성하고 읽는 작업 파일 ({repo-slug}-*.json)
|
|
140
|
+
snapshots/{owner}/{repo}/ # 다운로드된 코드 스냅샷 원본 (절대 직접 수정 금지)
|
|
141
|
+
wiki/{owner}/{repo}/ # 최종 Markdown 위키 출력
|
|
142
|
+
chunked/{owner}/{repo}/ # 진행 중인 섹션별 작업 및 세션 상태 보관 파일
|
|
143
|
+
freshness/state.json # 증분 업데이트 감지 시 사용하는 마지막 베이스라인 상태 파일
|
|
144
|
+
```
|