diff --git a/README-en.md b/README-en.md index 453dd64..f804078 100644 --- a/README-en.md +++ b/README-en.md @@ -11,7 +11,7 @@ [![][npm-release-shield]][npm-release-link] [![][npm-downloads-shield]][npm-downloads-link] [![][github-contributors-shield]][github-contributors-link] [![][github-forks-shield]][github-forks-link] [![][github-stars-shield]][github-stars-link] [![][github-issues-shield]][github-issues-link] [![][github-issues-pr-shield]][github-issues-pr-link] [![][github-license-shield]][github-license-link] -English · [中文](./README.md) +English · [中文](./README.md) · [日本語](./README-ja_JP.md)
diff --git a/README-ja_JP.md b/README-ja_JP.md new file mode 100644 index 0000000..837db65 --- /dev/null +++ b/README-ja_JP.md @@ -0,0 +1,209 @@ +
+
+
+

+ + deepcode-cli + +

+

Deep Code CLI

+ +[![][npm-release-shield]][npm-release-link] [![][npm-downloads-shield]][npm-downloads-link] [![][github-contributors-shield]][github-contributors-link] [![][github-forks-shield]][github-forks-link] [![][github-stars-shield]][github-stars-link] +[![][github-issues-shield]][github-issues-link] [![][github-issues-pr-shield]][github-issues-pr-link] [![][github-license-shield]][github-license-link] + +[English](./README-en.md) · [中文](./README.md) · 日本語 + +
+
+ +[Deep Code](https://github.com/lessweb/deepcode-cli) は、`deepseek-v4` モデルに最適化されたターミナル AI コーディングアシスタントです。深い思考(Deep Thinking)、推論努力(Reasoning Effort)の制御、Agent Skills、MCP(Model Context Protocol)統合をサポートしています。 + + +## インストール + +```bash +npm install -g @vegamo/deepcode-cli +``` + +任意のプロジェクトディレクトリで `deepcode` を実行して開始します。 + +![intro2](resources/intro2.png) + +## 設定 + +`~/.deepcode/settings.json` を作成します: + +```json +{ + "env": { + "MODEL": "deepseek-v4-pro", + "BASE_URL": "https://api.deepseek.com", + "API_KEY": "sk-..." + }, + "thinkingEnabled": true, + "reasoningEffort": "max" +} +``` + +この設定ファイルは [Deep Code VSCode 拡張機能](https://github.com/lessweb/deepcode) と共有されます — 一度設定すれば、どこでも使えます。 + +設定の詳細(多階層の優先順位、環境変数など)については、[docs/configuration_ja.md](docs/configuration_ja.md) を参照してください。 + +## 主な機能 + +### **スキル(Skills)** +Deep Code CLI はエージェントスキルをサポートしており、アシスタントの機能を拡張できます: + +スキルは以下の場所から、優先順位の高い順に検出されます: + +| スコープ | パス | 用途 | +| :--------- | :-------------------- | :---------------------------- | +| プロジェクト | `./.deepcode/skills/` | Deep Code のネイティブな場所 | +| プロジェクト | `./.agents/skills/` | クロスクライアント相互運用性 | +| ユーザー | `~/.deepcode/skills/` | Deep Code のネイティブな場所 | +| ユーザー | `~/.agents/skills/` | クロスクライアント相互運用性 | + +### **DeepSeek に最適化** +- DeepSeek モデルのパフォーマンスに特化してチューニングされています。 +- [Context Caching](https://api-docs.deepseek.com/guides/kv_cache) を利用してコストを削減できます。 +- [Thinking Mode](https://api-docs.deepseek.com/guides/thinking_mode) と Effort Control をネイティブにサポートしています。 + +## スラッシュコマンドとキーボードショートカット + +| スラッシュコマンド | 動作 | +|------------------|------------------------------------------------------------| +| `/` | スキル / コマンドメニューを開く | +| `/new` | 新しい会話を開始する | +| `/resume` | 続きから再開する以前の会話を選択する | +| `/continue` | アクティブな会話を続けるか、再開する会話を選択する | +| `/model` | モデル、思考モード、推論努力を切り替える | +| `/raw` | 表示モードを切り替える(Normal / Lite / Raw スクロールバック) | +| `/init` | AGENTS.md ファイルを初期化する(LLM プロジェクト指示) | +| `/skills` | 利用可能なスキルを一覧表示する | +| `/mcp` | MCP サーバーの状態と利用可能なツールを表示する | +| `/undo` | コードや会話を以前の状態に復元する | +| `/exit` | 終了する(`Ctrl+D` を 2 回でも可) | + +| キー | 動作 | +|------------------|------------------------------------------------------------| +| `Enter` | プロンプトを送信する | +| `Shift+Enter` | 改行を挿入する(`Ctrl+J` でも可) | +| `Ctrl+V` | クリップボードから画像を貼り付ける | +| `Esc` | 現在のモデルターンを中断する | +| `Ctrl+D` を 2 回 | Deep Code を終了する | + +## サポートされているモデル + +- `deepseek-v4-pro`(推奨) +- `deepseek-v4-flash` +- その他の OpenAI 互換モデル + +## FAQ + +### Deep Code に VSCode 拡張機能はありますか? + +はい。Deep Code はフル機能の VSCode 拡張機能を提供しており、[VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=vegamo.deepcode-vscode) から入手できます。拡張機能は CLI と `~/.deepcode/settings.json` 設定ファイルを共有しているため、ターミナルとエディタをシームレスに切り替えられます。 + +### Deep Code は画像の理解をサポートしていますか? + +Deep Code はマルチモーダル入力をサポートしています — `Ctrl+V` でクリップボードから画像を貼り付けられます。ただし、`deepseek-v4` はまだマルチモーダルに対応していません。一部のモデルはマルチモーダル機能を持っていますが、マルチターン対話のリクエストに厳しい制限があります。マルチモーダル入力には、最も統合が優れている Volcano Ark の `Doubao-Seed-2.0-pro` モデルの使用をおすすめします。 + +### タスク完了後に自動で Slack メッセージを送信するには? + +Slack の Webhook を呼び出すシェル通知スクリプトを作成し、`~/.deepcode/settings.json` の `notify` フィールドにそのスクリプトのフルパスを設定します。詳細な手順は [docs/notify_ja.md](docs/notify_ja.md) を参照してください。 + +### Web 検索を有効にするには? + +Deep Code には、ほとんどのユースケースで十分に機能する無料の Web Search ツールが組み込まれています。Web 検索にカスタムスクリプトを使いたい場合は、`~/.deepcode/settings.json` の `webSearchTool` フィールドにスクリプトのフルパスを設定してください。詳細な手順は次を参照してください: https://github.com/qorzj/web_search_cli + +### Coding Plan はサポートされていますか? + +はい。`~/.deepcode/settings.json` の `env.BASE_URL` を OpenAI 互換の API エンドポイントに設定するだけです。Volcano Ark の Coding Plan を例にすると: + +```json +{ + "env": { + "MODEL": "ark-code-latest", + "BASE_URL": "https://ark.cn-beijing.volces.com/api/coding/v3", + "API_KEY": "**************" + }, + "thinkingEnabled": true +} +``` + +### MCP を設定するには? + +Deep Code は MCP(Model Context Protocol)をサポートしており、GitHub、ブラウザ、データベースなどの外部サービスに接続できます。`settings.json` の `mcpServers` フィールドを設定して有効化し、`/mcp` コマンドで MCP サーバーの状態と利用可能なツールを確認できます。 + +詳細なセットアップ手順は次を参照してください: [docs/mcp_ja.md](docs/mcp_ja.md) + +### タスク完了後に通知を送信するように Deep Code を設定するには? + +AI アシスタントがタスクを完了すると、Deep Code は通知スクリプトを自動的に実行して、タスクの結果を指定されたチャネル(Slack、システム通知など)に送信できます。 + +詳細な設定手順は次を参照してください: [docs/notify_ja.md](docs/notify_ja.md) + +### Deep Code は YOLO モードのみのサポートですか? + +いいえ。Deep Code にはきめ細かな権限制御メカニズムが組み込まれており、AI アシスタントがシェルコマンドの実行、ファイルの読み書き、ネットワークアクセスなどを行う前に操作を確認できます。`settings.json` の `permissions` フィールドで、各権限スコープのポリシー(常に許可、常に確認、拒否)を設定できます。詳細は [docs/permission_ja.md](docs/permission_ja.md) を参照してください。 + +## コントリビューション + +コントリビューションを歓迎します!始め方は次のとおりです: + +```bash +# リポジトリをクローン +git clone https://github.com/lessweb/deepcode-cli.git +cd deepcode-cli + +# 依存関係をインストール +npm install + +# ローカル開発(型チェック + Lint + フォーマットチェック + バンドル) +npm run build + +# テストを実行 +npm test + +# グローバルにリンク(ローカルのグローバルインストール) +npm link +``` + +- PR を提出する前に `npm run check` が通ることを確認してください(型チェック + Lint + フォーマットチェック) +- エラーを避けるため、ビルド前に `npm run format` を実行することをおすすめします + +## ヘルプ + +- バグ報告や機能リクエストは GitHub Issues へ (https://github.com/lessweb/deepcode-cli/issues) + +## ライセンス + +- MIT + +## 応援のお願い + +このツールが役に立ったと感じたら、次の方法で応援をご検討ください: + +- GitHub で Star を付ける (https://github.com/lessweb/deepcode-cli) +- フィードバックや提案を送る +- 友人や同僚に共有する + + + + +[npm-release-link]: https://www.npmjs.com/package/@vegamo/deepcode-cli +[npm-release-shield]: https://img.shields.io/npm/v/@vegamo/deepcode-cli?color=4d6BFE&labelColor=black&logo=npm&logoColor=white&style=flat-square&cacheSeconds=1800 +[npm-downloads-link]: https://www.npmjs.com/package/@vegamo/deepcode-cli +[npm-downloads-shield]: https://img.shields.io/npm/dt/@vegamo/deepcode-cli?labelColor=black&style=flat-square&color=4d6BFE&cacheSeconds=1800 +[github-contributors-link]: https://github.com/lessweb/deepcode-cli/graphs/contributors +[github-contributors-shield]: https://img.shields.io/github/contributors/lessweb/deepcode-cli?color=4d6BFE&labelColor=black&style=flat-square&cacheSeconds=1800 +[github-forks-link]: https://github.com/lessweb/deepcode-cli/network/members +[github-forks-shield]: https://img.shields.io/github/forks/lessweb/deepcode-cli?color=4d6BFE&labelColor=black&style=flat-square&cacheSeconds=1800 +[github-stars-link]: https://github.com/lessweb/deepcode-cli/network/stargazers +[github-stars-shield]: https://img.shields.io/github/stars/lessweb/deepcode-cli?color=4d6BFE&labelColor=black&style=flat-square&cacheSeconds=1800 +[github-issues-link]: https://github.com/lessweb/deepcode-cli/issues +[github-issues-shield]: https://img.shields.io/github/issues/lessweb/deepcode-cli?color=4d6BFE&labelColor=black&style=flat-square&cacheSeconds=1800 +[github-issues-pr-link]: https://github.com/lessweb/deepcode-cli/pulls +[github-issues-pr-shield]: https://img.shields.io/github/issues-pr/lessweb/deepcode-cli?color=4d6BFE&labelColor=black&style=flat-square&cacheSeconds=1800 +[github-license-link]: https://github.com/lessweb/deepcode-cli/blob/main/LICENSE +[github-license-shield]: https://img.shields.io/github/license/lessweb/deepcode-cli?color=4d6BFE&labelColor=black&style=flat-square&cacheSeconds=1800 diff --git a/README-zh_CN.md b/README-zh_CN.md index cde0231..d6d35d9 100644 --- a/README-zh_CN.md +++ b/README-zh_CN.md @@ -11,7 +11,7 @@ [![][npm-release-shield]][npm-release-link] [![][npm-downloads-shield]][npm-downloads-link] [![][github-contributors-shield]][github-contributors-link] [![][github-forks-shield]][github-forks-link] [![][github-stars-shield]][github-stars-link] [![][github-issues-shield]][github-issues-link] [![][github-issues-pr-shield]][github-issues-pr-link] [![][github-license-shield]][github-license-link] -[English](README-en.md) · 中文 +[English](README-en.md) · 中文 · [日本語](README-ja_JP.md)
diff --git a/README.md b/README.md index 39cd12b..d7ef769 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ [![][npm-release-shield]][npm-release-link] [![][npm-downloads-shield]][npm-downloads-link] [![][github-contributors-shield]][github-contributors-link] [![][github-forks-shield]][github-forks-link] [![][github-stars-shield]][github-stars-link] [![][github-issues-shield]][github-issues-link] [![][github-issues-pr-shield]][github-issues-pr-link] [![][github-license-shield]][github-license-link] -[English](README-en.md) · 中文 +[English](README-en.md) · 中文 · [日本語](./README-ja_JP.md)
diff --git a/docs/agent-skills_ja.md b/docs/agent-skills_ja.md new file mode 100644 index 0000000..77cdf79 --- /dev/null +++ b/docs/agent-skills_ja.md @@ -0,0 +1,322 @@ +# エージェントスキル + +## 概要 + +スキルは、次のような指示セットに適しています。 + +- コードレビュー、リリース準備、レポート生成など、複数のタスクで繰り返し使うもの +- 毎回プロンプトに貼り付けるには長すぎる、または詳細すぎるもの +- テンプレート、スクリプト、スキーマ、サンプル、リファレンスドキュメントなどのリソースを伴うもの +- 「PDFフォームを処理する」「このプロジェクトのデータベースマイグレーションを作成する」のように、明確な状況で発動するもの + +次のような用途にはスキルを使わないでください。 + +- 一度きりのタスク要件 +- 短いリポジトリルール(通常は `AGENTS.md` に書くのが適切です) +- 外部システムへのライブな操作(通常はMCP(Model Context Protocol)ツールが適切です) + +## スキャン対象の場所 + +Deep Code CLIは以下の順序でスキルをスキャンします。複数のスキルが同じ `name` に解決された場合、最も優先度の高いものだけが有効になります。 + +| 優先度 | スコープ | パス | 用途 | +| -------- | ------- | --------------------- | ------- | +| 1 | プロジェクト | `./.deepcode/skills/` | Deep Codeネイティブのプロジェクトスキル | +| 2 | プロジェクト | `./.agents/skills/` | 他のエージェントクライアントと共有するプロジェクトスキル | +| 3 | ユーザー | `~/.deepcode/skills/` | Deep Codeネイティブのユーザースキル | +| 4 | ユーザー | `~/.agents/skills/` | 他のエージェントクライアントと共有するユーザースキル | +| 5 | グローバル | `built-in` | Deep Codeに同梱されているスキル | + +構成例: + +```text +.deepcode/ +└── skills/ + └── code-review/ + ├── SKILL.md + ├── checklist.md + └── scripts/ + └── collect-diff.sh +``` + +## 最小構成のスキル + +各スキルは専用のディレクトリに置き、`SKILL.md` を含める必要があります。 + +```markdown +--- +name: code-review +description: Review code changes for correctness, regressions, security risks, and missing tests. Use when the user asks for a review, PR review, diff review, or pre-merge check. +--- + +# Code Review + +Use a code review mindset. Prioritize bugs, behavioral regressions, security issues, +and missing tests over style comments. + +## Workflow + +1. Inspect the diff and relevant surrounding code. +2. List findings first, ordered by severity. +3. Include file and line references for every finding. +4. If there are no findings, say so and mention residual risks or test gaps. +``` + +## `SKILL.md` のフロントマター + +Deep Code CLIは `SKILL.md` の先頭にあるYAMLフロントマターを読み取ります。 + +| フィールド | 必須かどうか | Deep Codeの動作 | 推奨事項 | +| ----- | -------- | ------------------ | -------------- | +| `name` | 推奨 | スキルの一意な名前として使われます。未指定の場合、Deep Codeはディレクトリ名を使い、`_` を `-` に変換します。 | 小文字、数字、ハイフンを使い、ディレクトリ名と揃えてください。 | +| `description` | 推奨 | 自動マッチングに使われ、`/skills` やスラッシュメニューに表示されます。 | スキルが何をするか、いつ使うか、よくあるトリガーとなる語句を記述してください。 | +| `metadata.allow-implicit-invocation` | 任意 | `false` に設定すると自動マッチングの対象から外れますが、手動での選択は引き続き可能です。 | 手動専用のスキルに使ってください。 | + +例: + +```yaml +--- +name: db-migration +description: Create and review database migrations for this project. Use when the user asks to add columns, change schema, write migrations, or validate rollback behavior. +metadata: + allow-implicit-invocation: false +--- +``` + +> Deep Code CLIが現在解釈するのは上記のフィールドのみです。それ以外のフロントマターフィールドは、他クライアントとの互換性やドキュメント目的で役立つ場合がありますが、Deep Codeのツール権限を自動的に制限することはありません。 + +## 効果的な `description` の書き方 + +`description` は、スキルを見つけてもらうための最も重要なシグナルです。自動マッチングの際、Deep Codeがモデルに渡すのは各スキルの `name` と `description` だけなので、具体的に書くほど確実にマッチします。 + +推奨パターン: + +```text +. Use when . +``` + +良い例: + +```yaml +description: Extract tables from PDF files, fill PDF forms, and merge documents. Use when working with PDFs, forms, invoices, statements, or document extraction. +``` + +```yaml +description: Generate Lessweb routes, services, and Pydantic request models. Use when editing Lessweb projects, adding @Get/@Post endpoints, configuring IOC modules, or updating OpenAPI output. +``` + +避けるべき例: + +```yaml +description: Helps with documents +description: Useful project skill +description: Tooling instructions +``` + +チェックリスト: + +- トピックだけでなく、具体的な機能を明記する +- 期待される結果だけでなく、いつ使うのかを明記する +- ユーザーが入力しそうな語句を含める +- 関連するファイル形式、フレームワーク名、コマンド名、ドメイン名を含める +- 無関係なタスクでも発動してしまうような、広すぎる表現を避ける + +## スキル本文の構成 + +`SKILL.md` の本文は、一般の読者向けではなくエージェント向けに書いてください。直接的で、実行可能で、検証可能な内容に保ちます。 + +推奨構成: + +```markdown +# Skill Name + +Briefly state what this skill is for. + +## When to use + +- Use when ... +- Do not use when ... + +## Workflow + +1. Read ... +2. Run ... +3. Edit ... +4. Verify ... + +## Rules + +- Preserve ... +- Never ... +- Ask the user when ... + +## Examples + +... +``` + +執筆の原則: + +- 「まずスキーマを読む」「編集後にテストを実行する」のように、命令形のステップで書く +- 必ず守るべき制約は明示的なルールとして書く +- ファイル削除、データ移行、リクエスト送信といった高リスクな操作には境界を定義する +- 「設定ファイルがなければ、まずデフォルトのパスを探す」のように、よくある分岐を文書化する +- 長いリファレンス資料は `SKILL.md` の外に移す + +## 補助リソース + +スキルには `SKILL.md` と同じ階層にファイルを含めることができます。 + +```text +my-skill/ +├── SKILL.md +├── references/ +│ └── api.md +├── examples/ +│ └── request.json +├── scripts/ +│ └── validate.py +└── templates/ + └── report.md +``` + +`SKILL.md` が長くなりすぎたり、一覧性が損なわれたりする資料には補助ファイルを使ってください。 + +- 長いドキュメント、仕様、APIノートは `references/` に置く +- 入出力のサンプルは `examples/` に置く +- 再利用可能なコマンドは `scripts/` に置く +- ドキュメントやコードの雛形は `templates/` に置く +- 各補助ファイルをいつ参照すべきかを `SKILL.md` で説明する + +例: + +```markdown +## Workflow + +1. Read `references/schema.md` before changing generated types. +2. Use `templates/migration.sql` when creating a new migration. +3. Run `python scripts/check_migration.py ` before reporting completion. +``` + +## 呼び出し方法 + +Deep Code CLIはスキルの自動呼び出しと手動呼び出しの両方をサポートしています。 + +### 自動呼び出し + +ユーザーのメッセージごとに、Deep Codeは利用可能なスキルの `name` と `description` フィールドを確認し、タスクに合致するスキルを選択します。マッチしたスキルは現在のセッションに読み込まれます。 + +自動呼び出しのルール: + +- 一度読み込まれたスキルは、同じセッション内で再度読み込まれない +- `metadata.allow-implicit-invocation: false` が設定されたスキルは自動では読み込まれない +- マッチングでは現在の `AGENTS.md` の指示も考慮される +- マッチするスキルがなければ、何も読み込まれない + +### 手動呼び出し + +入力ボックスに `/` と入力するとスキルとコマンドのメニューが開くので、そこからスキルを選択します。利用可能なスキルの一覧は `/skills` で確認できます。 + +よく使うコマンド: + +| コマンド | 動作 | +| ------- | -------- | +| `/` | スキルとコマンドのメニューを開く | +| `/skills` | 利用可能なスキルを一覧表示する | +| `/` | メニューから該当するスキルを選択する | + +## スキルの有効化と無効化 + +`settings.json` の `enabledSkills` を使うと、スキルを名前単位で有効化・無効化できます。 + +```json +{ + "enabledSkills": { + "code-review": true, + "db-migration": false + } +} +``` + +ルール: + +- 記載されていないスキルはデフォルトで有効 +- スキルを `false` に設定すると、その解決名を持つスキャン済みスキルがすべて非表示になる +- プロジェクト設定はスキルごとにユーザー設定を上書きする + +詳細は [configuration_ja.md](configuration_ja.md) を参照してください。 + +## スキル vs. `AGENTS.md` vs. MCP + +| 仕組み | 適している用途 | 適していない用途 | +| --------- | -------- | ------------ | +| `AGENTS.md` | 長期的なリポジトリルール、コーディングスタイル、テストコマンド、コラボレーション上の取り決め | 再利用可能な複雑なワークフローや、プロジェクト横断のツール指示 | +| エージェントスキル | 再利用可能なワークフロー、ドメイン知識、テンプレート、スクリプト、リファレンスドキュメント | 単一タスク限りの一時的な要件 | +| MCP | 外部システム、ライブデータ、ブラウザ操作、データベース、GitHubなどのツール呼び出し | 純粋なテキストベースのワークフロー指示 | + +よくあるパターン: + +- リポジトリルールは `AGENTS.md` に置く +- 再利用可能なワークフローはスキルに置く +- 外部への操作はMCPツールに任せる + +## 例: プロジェクトリリーススキル + +```markdown +--- +name: release-check +description: Prepare and verify a project release. Use when the user asks to release, publish, bump version, update changelog, or run pre-release checks. +--- + +# Release Check + +Use this skill to prepare a safe release for this repository. + +## Workflow + +1. Read `package.json` and the existing changelog. +2. Inspect commits or diffs since the previous release tag. +3. Update version and changelog only when the user explicitly asks. +4. Run the project test and build commands. +5. Report the version, changed files, verification results, and remaining risks. + +## Rules + +- Do not publish packages unless the user explicitly asks. +- Do not create or push git tags without explicit approval. +- Preserve existing changelog style. +``` + +## トラブルシューティング + +### スキルが `/skills` に表示されない + +確認事項: + +1. ディレクトリがDeep Codeのスキャン対象の場所のいずれかにあるか +2. ファイル名が `SKILL.md` になっているか +3. `SKILL.md` が `.deepcode/skills/my-skill/SKILL.md` のように専用のスキルディレクトリ内にあるか +4. `enabledSkills` でそのスキルが `false` に設定されていないか +5. 同名のより高優先度のスキルに隠されていないか + +### 自動呼び出しが安定しない + +確認事項: + +1. `description` に明確なユースケースとトリガーとなる語句が含まれているか +2. スキルが広すぎて、モデルが適用範囲を推測できなくなっていないか +3. `metadata.allow-implicit-invocation` が `false` に設定されていないか +4. ユーザーのリクエストが、関連するドメインやファイル形式を十分明確に言及しているか + +### スキルが長すぎる + +推奨事項: + +1. 中核となるワークフローとルールは `SKILL.md` に残す +2. 長いドキュメントは `references/` に移す +3. 繰り返し使うコマンドは `scripts/` に移す +4. 各補助ファイルをエージェントがいつ読むべきかを説明する + +## 参考資料 + +- [Agent Skills Specification](https://agentskills.io/specification) diff --git a/docs/agents-md_ja.md b/docs/agents-md_ja.md new file mode 100644 index 0000000..52ae959 --- /dev/null +++ b/docs/agents-md_ja.md @@ -0,0 +1,220 @@ +# AGENTS.md + +`AGENTS.md` は、AIコーディングアシスタント向けのプロジェクト指示ファイルです。長期的に有効なリポジトリのルールを記録しておくことで、Deep Code は依存関係のインストール方法、テストの実行方法、コードの編集方法、変更の準備方法、チームの規約への従い方を把握できます。 + +「まずこのテストを実行して」「あのディレクトリは編集しないで」「PRの概要にはこれらの詳細を含めて」といった指示を繰り返し伝えているなら、それらを `AGENTS.md` に書いておきましょう。 + +## 記載すべき内容 + +`AGENTS.md` には、安定したプロジェクトルールを記載します。 + +- プロジェクト構成と重要なディレクトリ +- インストール、開発、ビルド、テストの各コマンド +- コーディングスタイル、命名規則、フォーマットのルール +- テストに関する期待事項と検証手順 +- コミット、プルリクエスト、リリースの規約 +- セキュリティ、設定、認証情報の取り扱いに関する注意事項 +- このリポジトリだけに適用されるAIとの協働ルール + +次のような内容には `AGENTS.md` を使わないでください。 + +- 「今回はログインページだけを編集して」のような、一度きりのタスク要件 +- 複雑で再利用可能なワークフロー(エージェントスキルの方が適しています) +- 外部サービスとの接続(MCP(Model Context Protocol)で設定する方が適しています) +- APIキー、パスワード、トークン、その他のシークレット + +## ファイルの作成 + +プロジェクト内で次のコマンドを実行します。 + +```text +/init +``` + +Deep Code が `AGENTS.md` の作成や更新を手伝ってくれます。手動で作成することもできます。 + +```bash +touch AGENTS.md +``` + +Deep Code 専用のプロジェクト指示を用意したい場合は、次のようにします。 + +```bash +mkdir -p .deepcode +touch .deepcode/AGENTS.md +``` + +一般的な選択肢は次のとおりです。 + +| ファイル | 適した用途 | +| ---- | -------- | +| `AGENTS.md` | 複数のAIコーディングツールから参照されるべきルール | +| `.deepcode/AGENTS.md` | Deep Code だけを対象とするルール | +| `~/.deepcode/AGENTS.md` | プロジェクト指示を持たないリポジトリ向けの個人的なデフォルト設定 | + +## 推奨される構成 + +短く、明確で、実行に移せる内容を心がけましょう。まずは次のようなセクションから始めるとよいでしょう。 + +```markdown +# Repository Guidelines + +## Project Structure + +主要なディレクトリと、新しいコードをどこに置くべきかを説明します。 + +## Development Commands + +- `npm install` — 依存関係をインストールします。 +- `npm test` — テストスイートを実行します。 +- `npm run build` — プロジェクトをビルドします。 + +## Coding Style + +フォーマット、命名、フレームワークの規約を説明します。 + +## Testing + +どのような場合にテストを追加すべきか、どのコマンドを実行すべきかを説明します。 + +## Pull Requests + +コミットのスタイル、PRのチェックリスト、スクリーンショット、リリースノートについて説明します。 + +## Agent Notes + +編集を避けるべきファイルや、完了前に実行すべきチェックなど、AIアシスタント向けのルールを列挙します。 +``` + +すべてのセクションが必要なわけではありません。そのリポジトリで役立つものだけを残してください。 + +## 記述の原則 + +### 具体的なコマンドを書く + +良い例: + +```markdown +## Development Commands + +- `npm install` — 依存関係をインストールします。 +- `npm test` — すべてのテストを実行します。 +- `npm run build` — 型チェックを行い、CLIをビルドします。 +``` + +避けるべき例: + +```markdown +仕上げる前にいつものコマンドを実行してください。 +``` + +### 明示的なルールを書く + +良い例: + +```markdown +## Testing + +動作を変更する際はテストを追加または更新してください。完了を報告する前に、 +テストのみの変更なら `npm test` を、コードの変更なら `npm run build` を実行してください。 +``` + +避けるべき例: + +```markdown +すべてが正しく動くことを確認してください。 +``` + +### リポジトリの事実を書く + +良い例: + +```markdown +## Project Structure + +- `src/` にはアプリケーションコードが含まれます。 +- `tests/` には自動テストが含まれます。 +- `docs/` にはユーザー向けドキュメントが含まれます。 +``` + +避けるべき例: + +```markdown +これは普通のTypeScriptプロジェクトです。 +``` + +### 安全上の境界を書く + +良い例: + +```markdown +## Security + +APIキーやトークンをコミットしないでください。ローカルの認証情報には +`~/.deepcode/settings.json` を使い、プロジェクト内のサンプルは伏せ字にしてください。 +``` + +避けるべき例: + +```markdown +シークレットの扱いには注意してください。 +``` + +## 例 + +完全な `AGENTS.md` の例を示します。 + +```markdown +# Repository Guidelines + +## Project Structure + +- `src/` にはアプリケーションコードが含まれます。 +- `src/tests/` には自動テストが含まれます。 +- `docs/` にはユーザー向けドキュメントが含まれます。 +- `config/` にはプロジェクト設定の例が含まれます。 + +## Development Commands + +- `npm install` — 依存関係をインストールします。 +- `npm test` — 自動テストを実行します。 +- `npm run build` — チェックを実行し、CLIをビルドします。 + +## Coding Style + +TypeScriptを使用します。コードは読みやすく保ち、明確な名前を優先し、既存の +フォーマットスタイルに従ってください。無関係なリファクタリングを持ち込まないでください。 + +## Testing + +動作を変更する際はテストを追加してください。まず関連する最小範囲のテストを実行し、 +可能であれば完了を報告する前に `npm test` または `npm run build` を実行してください。 + +## Agent Notes + +- シークレットや生成されたローカルファイルをコミットしないでください。 +- ユーザーによる既存の変更を保持してください。 +- 実行できなかった検証手順があれば説明してください。 +``` + +## AGENTS.md・スキル・MCPの使い分け + +| 仕組み | 適した用途 | +| --------- | -------- | +| `AGENTS.md` | 長期的に有効なリポジトリのルール、コマンド、スタイル、検証手順 | +| エージェントスキル | 再利用可能なワークフロー、ドメイン知識、テンプレート、スクリプト、リファレンスドキュメント | +| MCP(Model Context Protocol) | GitHub、ブラウザ、データベースなどの外部ツールやライブデータ | + +よくあるパターンは次のとおりです。 + +- 「このプロジェクトの動かし方」は `AGENTS.md` に書く +- 「この種のタスクの進め方」はエージェントスキルに書く +- 外部サービスを必要とする作業にはMCP(Model Context Protocol)を使う + +## メンテナンスのヒント + +- プロジェクトが変わったらコマンドを更新する +- 古くなったルールは削除する +- 簡潔さを保ち、頻出・重要・見落としやすい規約を優先する +- シークレットを含めない +- 現在のタスクにしか適用されないルールは、`AGENTS.md` ではなく現在の会話の中で伝える diff --git a/docs/configuration_ja.md b/docs/configuration_ja.md new file mode 100644 index 0000000..6eb48b2 --- /dev/null +++ b/docs/configuration_ja.md @@ -0,0 +1,217 @@ +# Deep Code の設定 + +## 設定の優先順位 + +設定は以下の優先順位で適用されます(番号が小さい設定ソースは、番号が大きい設定ソースによって上書きされます)。 + +| 階層 | 設定ソース | 説明 | +| ----- | -------------------- | ---------------------------------------------- | +| 1 | デフォルト値 | アプリケーション内にハードコードされたデフォルト値 | +| 2 | ユーザー設定ファイル | 現在のユーザーに対するグローバル設定 | +| 3 | プロジェクト設定ファイル | プロジェクト固有の設定 | +| 4 | 環境変数 | システム全体またはセッション固有の変数 | + +## 設定ファイル + +Deep Code は永続的な設定に `settings.json` ファイルを使用し、2 つの保存場所をサポートしています。 + +| ファイル種別 | 場所 | 適用範囲 | +| ------------------- | ----------------------------------------- | --------------------------------------------------------------------- | +| ユーザー設定ファイル | `~/.deepcode/settings.json` | 現在のユーザーのすべての Deep Code セッションに適用されます。 | +| プロジェクト設定ファイル | `/.deepcode/settings.json` | その特定のプロジェクトで Deep Code を実行したときのみ有効になります。プロジェクト設定はユーザー設定を上書きします。 | + +### `settings.json` で利用可能な設定 + +以下は `settings.json` でサポートされているすべてのトップレベルフィールドと、`env` 内のサブフィールドです。 + +| フィールド | 型 | 説明 | +| ------------------ | ------- | --------------------------------------------------------------------------- | +| `env` | object | 環境変数のグループ(下記のサブフィールド表を参照) | +| `model` | string | モデル名。`env.MODEL` より優先されます | +| `thinkingEnabled` | boolean | 思考モードを有効にするかどうか(DeepSeek V4 シリーズではデフォルトで有効) | +| `reasoningEffort` | string | 推論努力の強度。`"high"` または `"max"`(デフォルトは `"max"`) | +| `debugLogEnabled` | boolean | デバッグログ出力を有効にする(デフォルトは `false`) | +| `telemetryEnabled` | boolean | 匿名の利用状況レポートを有効にする(デフォルトは `true`) | +| `notify` | string | タスク完了通知スクリプトのフルパス(例: Slack 通知スクリプト) | +| `webSearchTool` | string | カスタム Web 検索スクリプトのフルパス | +| `mcpServers` | object | MCP サーバーの設定(キーはサービス名、値は McpServerConfig オブジェクト) | +| `temperature` | number | LLM のサンプリング温度。`0` から `2` まで | +| `enabledSkills` | object | スキルごとの有効/無効マップ。キーはスキル名 | +| `statusline` | object | ステータスラインプラグイン([statusline_ja.md](./statusline_ja.md) を参照) | + +#### `env` サブフィールド + +| フィールド | 型 | 説明 | +| ----------------- | ------ | ---------------------------------------------------------------- | +| `MODEL` | string | モデル名。例: `"deepseek-v4-pro"`、`"deepseek-v4-flash"` | +| `BASE_URL` | string | API リクエストのベース URL。例: `"https://api.deepseek.com"` | +| `API_KEY` | string | API キー | +| `TEMPERATURE` | string | チャット補完のサンプリング温度。`"0"` から `"2"` まで | +| `THINKING_ENABLED`| string | 思考モードを有効にする | +| `REASONING_EFFORT`| string | 推論努力の強度 | +| `DEBUG_LOG_ENABLED`| string| デバッグログ出力を有効にする | +| `TELEMETRY_ENABLED`| string| 匿名の利用状況レポートを有効にする | +| `` | string | カスタム環境変数 | + +#### `thinkingEnabled` — 思考モード + +DeepSeek の思考モードを有効にするかどうかを設定します。`true` で有効、`false` で無効になります。 + +- `deepseek-v4-pro` と `deepseek-v4-flash` では、思考モードは**デフォルトで有効**です。 +- その他のモデルでは、思考モードは**デフォルトで無効**です。 + +#### `reasoningEffort` — 推論努力の強度 + +思考モードが有効な場合に、モデルの推論の深さを制御します。 + +| 値 | 説明 | +| ------ | --------------------------------------------------------- | +| `max` | 最大の推論深度(デフォルト) | +| `high` | 比較的少ないトークン使用量で、高い推論深度を実現 | + +#### `notify` — タスク完了通知 + +シェルスクリプトのフルパスを設定します。AI アシスタントが一連のタスクを完了すると、そのスクリプトが自動的に実行され、通知の送信(例: Slack メッセージ)などに利用できます。 + +notify スクリプトの実行時には、以下のコンテキストが環境変数として渡されます。 + +| 変数 | 説明 | +|----------|-------------| +| `DURATION` | セッションの実行時間(秒、整数) | +| `STATUS` | セッションの状態: `"completed"` または `"failed"` | +| `FAIL_REASON` | 失敗理由(失敗時のみ設定) | +| `BODY` | AI アシスタントの最後の返信のテキスト内容 | +| `TITLE` | セッションのタイトル(再開リストのタイトルと一致) | + +```json +{ + "notify": "/path/to/notify-script.sh" +} +``` + +> 詳細な設定例(Slack、Feishu、ターミナル通知、システム通知など)については、[notify_ja.md](notify_ja.md) を参照してください。 + +#### `webSearchTool` — カスタム Web 検索 + +Deep Code には無料で利用できる Web 検索ツールが組み込まれています。独自の検索ロジックが必要な場合は、`webSearchTool` に実行可能スクリプトのフルパスを設定してください。 + +```json +{ + "webSearchTool": "/path/to/my-search-script.sh" +} +``` + +このスクリプトは検索クエリを引数として受け取り、AI 向けに JSON 形式で結果を出力します。 + +#### `enabledSkills` — スキルの有効化 + +スキルスキャン時にスキルを含めるかどうかを制御します。キーは解決済みのスキル名で、値は boolean である必要があります。 + +```json +{ + "enabledSkills": { + "skill-writer": false, + "code-review": true + } +} +``` + +- 設定に含まれていないスキルは、デフォルトで有効になります。 +- あるスキルを `false` に設定すると、プロジェクトおよびユーザーのスキルルート全体で、その解決済み `name` を持つすべてのスキルが非表示になります。 +- プロジェクト設定は、スキルごとにユーザー設定を上書きします。プロジェクト設定にそのスキルの記載がない場合は、ユーザー設定が使用されます。 + +#### `mcpServers` — MCP サーバー + +MCP(Model Context Protocol)サーバーの設定です。値はキーと値のペアで、キーはサービス名、値はサーバー設定オブジェクトです。 + +```json +{ + "mcpServers": { + "": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx" + } + } + } +} +``` + +| McpServerConfig フィールド | 型 | 必須 | 説明 | +| --------------------- | -------- | -------- | ------------------------------------------------------------------------ | +| `command` | string | はい | 実行ファイルのパスまたはコマンド(例: `npx`、`node`、`python`) | +| `args` | string[] | いいえ | コマンドに渡す引数のリスト | +| `env` | object | いいえ | MCP サーバープロセスに渡す環境変数 | + +> `command` が `npx` の場合、Deep Code は自動的に引数の先頭に `-y` を追加します。 + +MCP の詳しい使い方については、[mcp_ja.md](mcp_ja.md) を参照してください。 + +#### `debugLogEnabled` — デバッグログ + +`true` に設定すると詳細なデバッグログが有効になります(デフォルトは `false`)。API 呼び出しやツール実行のトラブルシューティングに役立ちます。 + +#### `telemetryEnabled` — 匿名の利用状況レポート + +`false` に設定すると匿名の利用状況レポートを無効にできます(デフォルトは `true`)。レポートに含まれるのは匿名のマシン識別子のみで、会話内容、コード、API キーは含まれません。 + +環境変数で無効にすることもできます。 + +```bash +DEEPCODE_TELEMETRY_ENABLED=0 deepcode +``` + +## 環境変数の優先順位 + +環境変数はアプリケーションを設定する一般的な方法であり、特に機密情報(api-key など)や環境ごとに変わりうる設定に適しています。 + +### 優先順位の原則 + +環境変数の優先順位は、「設定がより具体的でローカルであるほど優先度が高い」というロジックと、「env ファイルはデフォルトで既存の環境を保護し、システム変数は env ファイルを上書きする」という上書きルールに従います。(settings.json 内の `env` オブジェクトは、env ファイルの一種と考えることができます。) + +優先度のレベル(低いものから高いものへ): +1. `settings.json` のトップレベルで定義された `env` – ツール全体とそのすべてのサブプロセスに対する一般的な設定(グローバル変数)です。外側の環境変数で上書きできますが、環境変数の KEY からは `DEEPCODE_` プレフィックスが取り除かれます。 +2. `settings.json` の `mcpServers` 内で定義された `env` – 特定の MCP サービスに対する最も具体的な設定(ローカル変数)です。外側の環境変数で上書きできますが、KEY からは `MCP_` プレフィックスが取り除かれます。 +3. シェル/システム環境変数 – オペレーティングシステムレベルです。 + +### シナリオ + +#### 1. モデルの api_key と base_url を設定する + +以下の優先順位で適用されます(番号が小さいものは番号が大きいものによって上書きされます)。api_key を例にします。 + +1. ハードコードされたデフォルト値: `""` +2. ユーザーレベルの settings.json: `{"env": {"API_KEY": "abc123"}}` +3. プロジェクトレベルの settings.json: `{"env": {"API_KEY": "abc123"}}` +4. システム環境変数: `DEEPCODE_API_KEY=abc123 deepcode` + +#### 2. model、thinkingEnabled、reasoningEffort を設定する + +以下の優先順位で適用されます(番号が小さいものは番号が大きいものによって上書きされます)。thinkingEnabled を例にします。 + +1. ハードコードされたデフォルト値: `true` +2. ユーザーレベルの settings.json: `{"env": {"THINKING_ENABLED": "true"}}` +3. ユーザーレベルの settings.json: `{"thinkingEnabled": true}` +4. プロジェクトレベルの settings.json: `{"env": {"THINKING_ENABLED": "true"}}` +5. プロジェクトレベルの settings.json: `{"thinkingEnabled": true}` +6. システム環境変数: `DEEPCODE_THINKING_ENABLED=true deepcode` + +#### 3. notify や webSearchTool などの外部スクリプト向けに環境変数を設定する + +以下の優先順位で適用されます(番号が小さいものは番号が大きいものによって上書きされます)。notify を例にします。 + +1. ハードコードされたデフォルト値: `os.environ.get('WEBHOOK', '...') # notify スクリプトのコード` +2. ユーザーレベルの settings.json: `{"env": {"WEBHOOK": "..."}}` +3. プロジェクトレベルの settings.json: `{"env": {"WEBHOOK": "true"}}` +4. システム環境変数: `DEEPCODE_WEBHOOK=... deepcode` + +#### 4. MCP サービス向けに環境変数を設定する + +以下の優先順位で適用されます(番号が小さいものは番号が大きいものによって上書きされます)。GitHub MCP サーバーを例にします。 + +1. ユーザーレベルの settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}` +2. ユーザーレベルの settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}` +3. プロジェクトレベルの settings.json: `{"mcpServers":{"github":{"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"..."}}}}` +4. プロジェクトレベルの settings.json: `{"env": {"MCP_GITHUB_PERSONAL_ACCESS_TOKEN": "..."}}` +5. システム環境変数: `DEEPCODE_MCP_GITHUB_PERSONAL_ACCESS_TOKEN=... deepcode` diff --git a/docs/mcp_ja.md b/docs/mcp_ja.md new file mode 100644 index 0000000..fb86141 --- /dev/null +++ b/docs/mcp_ja.md @@ -0,0 +1,200 @@ +# Deep Code CLI MCP 設定ガイド + +Deep Code CLI は MCP(Model Context Protocol)に対応しており、AI アシスタントを GitHub、ブラウザ、データベースなどの外部ツールやサービスと接続できます。 + +## 概要 + +MCP を設定すると、Deep Code は次のことができるようになります。 + +- GitHub リポジトリの操作(Issue の閲覧、PR の作成、コード検索など) +- ブラウザの操作(スクリーンショット、クリック、フォーム入力など) +- ファイルシステムへのアクセス +- データベースや API への接続 +- ...そのほか MCP プロトコルに対応したあらゆる外部サービス + +Deep Code では、MCP ツールは `mcp____` という形式で命名されます。例: `mcp__github__search_code` + +## MCP サーバーの設定 + +`~/.deepcode/settings.json` を編集し、`mcpServers` フィールドを追加します。 + +```json +{ + "env": { + "MODEL": "deepseek-v4-pro", + "BASE_URL": "https://api.deepseek.com", + "API_KEY": "sk-..." + }, + "thinkingEnabled": true, + "reasoningEffort": "max", + "mcpServers": { + "": { + "command": "", + "args": ["", ""], + "env": { + "": "" + } + } + } +} +``` + +### 設定フィールド + +| フィールド | 型 | 必須 | 説明 | +| --------- | -------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `command` | string | はい | MCP サーバー実行ファイルのパスまたはコマンド(例: `npx`、`node`、`python`)。コマンドが `npx` の場合、Deep Code は自動的に引数の先頭へ `-y` を追加します。 | +| `args` | string[] | いいえ | コマンドに渡す引数のリスト | +| `env` | object | いいえ | MCP サーバープロセスに渡す環境変数(API キーなど) | + +## よく使われる MCP の例 + +### GitHub MCP + +Deep Code から GitHub リポジトリを直接操作できるようになります(コード検索、Issue/PR の管理、ファイルの読み書きなど)。 + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx" + } + } + } +} +``` + +> GitHub Personal Access Token は [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens) で生成できます。 + +### ブラウザ操作(Playwright) + +Deep Code でブラウザを操作し、スクリーンショットの取得やページ操作などを行えるようになります。 + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + } + } +} +``` + +### ファイルシステム + +指定したディレクトリ内のファイルを Deep Code が読み書きできるようになります。 + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"] + } + } +} +``` + +### カスタム Python MCP + +```json +{ + "mcpServers": { + "my-tool": { + "command": "python", + "args": ["-m", "my_mcp_server"], + "env": { + "API_KEY": "xxx" + } + } + } +} +``` + +## 完全な設定例 + +GitHub と Playwright の両方の MCP サーバーを設定した、完全な `~/.deepcode/settings.json` の例を以下に示します。 + +```json +{ + "env": { + "MODEL": "deepseek-v4-pro", + "BASE_URL": "https://api.deepseek.com", + "API_KEY": "sk-xxxxxxxxxxxx" + }, + "thinkingEnabled": true, + "reasoningEffort": "max", + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx" + } + }, + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + } + } +} +``` + +## MCP の使い方 + +設定が完了したら `deepcode` を起動し、チャットで `/mcp` と入力すると、設定済みのすべての MCP サーバーの状態と、各サーバーが提供するツールの一覧を確認できます。 + +会話の中で MCP ツール名を使うだけで、そのツールを呼び出せます。例: + +``` +Help me search for issues in the deepcode-cli repository on GitHub +``` + +AI が自動的に `mcp__github__search_issues` ツールを呼び出して処理を完了します。 + +## ツールの命名規則 + +MCP ツール名は `mcp____` の 3 つの部分で構成されます。 + +| サービス | ツール名 | 完全な呼び出し名 | +| ---------- | ----------------------- | ------------------------------------------- | +| github | search_code | `mcp__github__search_code` | +| github | create_pull_request | `mcp__github__create_pull_request` | +| playwright | browser_navigate | `mcp__playwright__browser_navigate` | +| playwright | browser_take_screenshot | `mcp__playwright__browser_take_screenshot` | + +各サーバーが提供するツールの一覧は `/mcp` で確認できます。 + +## トラブルシューティング + +### 起動に失敗する場合 + +MCP サーバーの起動に失敗する場合は、次の点を確認してください。 + +1. `command` がインストールされているか(例: `npx` には Node.js が必要です) +2. `env` に設定した環境変数が正しいか(例: `GITHUB_PERSONAL_ACCESS_TOKEN`) +3. `deepcode` を実行しているターミナルがネットワークにアクセスできるか + +### ツールが表示されない場合 + +1. `settings.json` の `mcpServers` フィールドの書式が正しいか確認する +2. deepcode の起動後、`/mcp` でサーバーの状態を確認する +3. サーバーの状態がエラーになっている場合は、エラーメッセージをもとにデバッグする + +### Windows ユーザー向け + +Windows では、Deep Code CLI が `.cmd` コマンドに対するシェルサポートを自動的に追加します。MCP のコマンドがバッチスクリプトの場合は、ファイル名が `.cmd` で終わっていることを確認してください。 + +## 独自の MCP サーバーを作成する + +MCP サーバーは [Model Context Protocol](https://modelcontextprotocol.io/) の仕様に従い、JSON-RPC 2.0 を使って通信します。次のメソッドを実装していれば、どの言語でも MCP サーバーを作成できます。 + +1. `initialize` — ハンドシェイクとプロトコルのネゴシエーション +2. `tools/list` — 利用可能なツールの一覧を返す +3. `tools/call` — ツール呼び出しを実行する + +詳しくは [MCP 公式ドキュメント](https://modelcontextprotocol.io/) を参照してください。 diff --git a/docs/notify_ja.md b/docs/notify_ja.md new file mode 100644 index 0000000..6d1f0fe --- /dev/null +++ b/docs/notify_ja.md @@ -0,0 +1,211 @@ +# Deep Code タスク完了通知 + +AIアシスタントが一連のタスクを終えたとき、Deep Code は通知スクリプトを自動的に実行し、タスクの結果を任意のチャネル(Slack、システム通知など)へ送信できます。 + +## 仕組み + +`settings.json` の `notify` フィールドに、実行可能なスクリプトのフルパスを設定します。AIアシスタントがタスクの応答を完了するたびに、Deep Code はそのスクリプトを実行し、コンテキストを環境変数として注入します。 + +## 注入される環境変数 + +| 変数 | 説明 | +|----------|-------------| +| `DURATION` | セッションの所要時間(秒、整数) | +| `STATUS` | セッションのステータス: `"completed"` または `"failed"` | +| `FAIL_REASON` | 失敗の理由(失敗時のみ設定) | +| `BODY` | AIアシスタントの最後の応答のテキスト内容 | +| `TITLE` | セッションのタイトル(再開リストのタイトルと同じ) | + +## 設定方法 + +`~/.deepcode/settings.json` を編集し、`notify` フィールドを追加します。 + +```json +{ + "env": { + "MODEL": "deepseek-v4-pro", + "BASE_URL": "https://api.deepseek.com", + "API_KEY": "sk-..." + }, + "thinkingEnabled": true, + "reasoningEffort": "max", + "notify": "/path/to/your-notify-script.sh" +} +``` + +Slack の Webhook URL など、通知スクリプト用のカスタム環境変数を `env` に設定することもできます。 + +```json +{ + "env": { + "MODEL": "deepseek-v4-pro", + "BASE_URL": "https://api.deepseek.com", + "API_KEY": "sk-...", + "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/*****/****/**********" + }, + "notify": "/Users/you/.deepcode/notify-slack.sh" +} +``` + +これらの `env` の変数は、スクリプトの実行環境に注入されます。 + +## Slack 通知 + +### 1. Slack Webhook URL を取得する + +1. [Slack App](https://api.slack.com/apps) を作成します +2. App のページで **Incoming Webhooks** → **Add New Webhook to Workspace** に進み、Webhook URL を生成します + +### 2. 通知スクリプトを作成する + +`~/.deepcode/notify-slack.sh` を作成します。 + +```bash +#!/usr/bin/env bash +SLACK_WEBHOOK_URL="${SLACK_WEBHOOK_URL:-}" +CURRENT_DIR=$(pwd) +BRANCH=$(git branch --show-current 2>/dev/null) +curl -X POST "$SLACK_WEBHOOK_URL" \ + -H "Content-type: application/json" \ + --data "{ + \"text\": \"✅ Deep Code task completed\n · cwd: $CURRENT_DIR\n · Branch: $BRANCH\n · Duration: $DURATION s\" + }" +``` + +スクリプトに実行権限を付与します。 + +```bash +chmod +x ~/.deepcode/notify-slack.sh +``` + +### 3. settings.json を設定する + +```json +{ + "env": { + "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/*****/****/**********" + }, + "notify": "/Users/you/.deepcode/notify-slack.sh" +} +``` + +> Python 版のスクリプトも利用できます。任意のカスタム環境変数を `env` 経由で渡して参照できます。 + +## Feishu / WeCom Webhook 通知 + +`node` で JSON を組み立て(特殊文字を自動エスケープ)、`curl` で送信します。`WEBHOOK_URL` は `env` 経由で渡します。 + +```bash +#!/bin/bash +WEBHOOK_URL="${WEBHOOK_URL:-}" + +STATUS="${STATUS:-completed}" +TITLE="${TITLE:-Untitled}" +DURATION="${DURATION:-0}" +BODY="${BODY:-(no output)}" + +PAYLOAD=$(node -e " +process.stdout.write(JSON.stringify({ + msg_type: 'interactive', + card: { + header: { title: { tag: 'plain_text', content: 'DeepCode: ' + process.env.TITLE + ' ' + process.env.STATUS + ' [' + process.env.DURATION + 's]' } }, + elements: [{ tag: 'markdown', content: (process.env.BODY || '').slice(0, 2000) || '(no output)' }] + } +})) +") + +curl -s -X POST "$WEBHOOK_URL" \ + -H "Content-Type: application/json" \ + -d "$PAYLOAD" +``` + +```json +{ + "env": { + "WEBHOOK_URL": "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxx" + }, + "notify": "/Users/you/.deepcode/notify-feishu.sh" +} +``` + +`WEBHOOK_URL` は、お使いの Feishu ボットの Webhook URL に置き換えてください。このパターンは、JSON ペイロードの形式を調整するだけで、他の Webhook ベースの通知(Slack、WeCom など)にも応用できます。 + +## ターミナル通知(iTerm2 / Windows Terminal) + +iTerm2 や Windows Terminal では、OSC 9 エスケープシーケンスを使うことで、依存関係なしにネイティブなターミナル通知を表示できます。 + +`~/.deepcode/notify.sh` を作成します。 + +```bash +#!/bin/bash +# iTerm2 / Windows Terminal の OSC 9 通知 +printf '\x1b]9;DeepCode: task %s (%ss)\x07' "${STATUS:-completed}" "${DURATION}" +``` + +```json +{ + "notify": "/Users/you/.deepcode/notify.sh" +} +``` + +Git Bash を使っている Windows ユーザーは同じスクリプトをそのまま利用できます。あるいは、`.bat` スクリプトを作成する方法もあります。 + +```batch +@echo off +REM Windows Terminal の OSC 9 通知 +echo \x1b]9;DeepCode: task %STATUS% (%DURATION%s)\x07 +``` + +## macOS システム通知 + +```bash +#!/bin/bash +# macOS システム通知 +osascript -e "display notification \"Task ${STATUS:-completed}, took ${DURATION}s\" with title \"DeepCode\"" +``` + +```json +{ + "notify": "/Users/you/.deepcode/notify.sh" +} +``` + +## Linux システム通知 + +`libnotify-bin` が必要です。 + +```bash +sudo apt install libnotify-bin # Debian/Ubuntu +``` + +`~/.deepcode/notify.sh` を作成します。 + +```bash +#!/bin/bash +# Linux の notify-send 通知 +notify-send "DeepCode" "Task ${STATUS:-completed}, took ${DURATION}s" +``` + +```json +{ + "notify": "/home/you/.deepcode/notify.sh" +} +``` + +## Windows msg ポップアップ通知 + +```batch +@echo off +REM Windows の msg ポップアップ通知 +msg %USERNAME% "DeepCode: task %STATUS% (%DURATION%s)" +``` + +```json +{ + "notify": "C:\\Users\\you\\.deepcode\\notify.bat" +} +``` + +## カスタム通知スクリプト + +注入される環境変数と、`env` 経由で渡した任意の追加変数を使って、任意の言語(Python、Node.js、Ruby など)で独自の通知スクリプトを作成できます。 diff --git a/docs/permission_ja.md b/docs/permission_ja.md new file mode 100644 index 0000000..eb6b2b6 --- /dev/null +++ b/docs/permission_ja.md @@ -0,0 +1,100 @@ +# Deep Code の権限メカニズム + +Deep Code には、きめ細かな権限制御メカニズムが備わっています。AI アシスタントがツール呼び出し(シェルコマンドの実行、ファイルの読み書き、ネットワークアクセスなど)を実行する前に、システムは設定されたポリシーに基づいて、自動許可・自動拒否・対話的な確認プロンプトのいずれで処理するかを判断します。 + +## 概要 + +AI アシスタントがツールを呼び出すたびに、システムは関係する**権限スコープ**を自動的に分析し、`settings.json` の権限設定に基づいて判断を下します。ユーザーの確認が必要な操作については、ターミナルに対話式のプロンプトが表示され、次の選択肢から選べます。 + +- **Yes** — 今回のみ許可する +- **Yes, and always allow** — 今回許可し、さらにそのスコープをプロジェクト設定に永続的に保存して、以降の呼び出しではプロンプトをスキップする +- **No** — この操作を拒否する + +## 権限スコープ + +Deep Code では、ツール呼び出しにおけるさまざまなリスクシナリオをカバーする、次の 10 種類の権限スコープを定義しています。 + +| 権限スコープ | 説明 | +| ---------------- | ----------- | +| `read-in-cwd` | 現在のワークスペース内のファイルを読み取る | +| `read-out-cwd` | 現在のワークスペース外のファイルを読み取る | +| `write-in-cwd` | 現在のワークスペース内でファイルを作成または上書きする | +| `write-out-cwd` | 現在のワークスペース外でファイルを作成または上書きする | +| `delete-in-cwd` | 現在のワークスペース内のファイルを削除する | +| `delete-out-cwd` | 現在のワークスペース外のファイルを削除する | +| `query-git-log` | Git 履歴を参照する(例: `git log`、`git show`、`git blame`) | +| `mutate-git-log` | Git 履歴を変更する(例: `git commit`、`git rebase`、`git tag`) | +| `network` | ネットワークにアクセスする(例: `curl`、`npm install`) | +| `mcp` | MCP(Model Context Protocol)の外部ツールを呼び出す | + +このほかに、LLM がコマンドの副作用を分類できない場合に使用される特別な `unknown` スコープがあります。**`unknown` は常に確認プロンプトを表示します**。 + +## 権限設定 + +権限は、`~/.deepcode/settings.json`(ユーザーレベル)または `.deepcode/settings.json`(プロジェクトレベル)の `permissions` フィールドで設定します。 + +```json +{ + "permissions": { + "allow": [], + "deny": [], + "ask": [], + "defaultMode": "allowAll" + } +} +``` + +### 設定フィールド + +| フィールド | 型 | 説明 | +| ----- | ---- | ----------- | +| `allow` | `string[]` | 常に自動許可する権限スコープ | +| `deny` | `string[]` | 常に自動拒否する権限スコープ | +| `ask` | `string[]` | 常に確認プロンプトを表示する権限スコープ | +| `defaultMode` | `"allowAll"` \| `"askAll"` | `allow`/`deny`/`ask` に明示的に列挙されていないスコープに対するデフォルトの動作。デフォルト値は `"allowAll"` | + +### 優先順位のルール + +1 つのツール呼び出しが複数の権限スコープに関係する場合、次の優先順位で判断されます。 + +1. いずれかのスコープが `deny` に一致する場合 → **拒否** +2. いずれかのスコープが `ask` に一致する場合 → **確認プロンプトを表示** +3. すべてのスコープが `allow` に含まれる場合 → **自動許可** +4. それ以外の場合 → `defaultMode` に従う + +### 例: 緩和モード(デフォルト) + +```json +{ + "permissions": { + "defaultMode": "allowAll" + } +} +``` + +デフォルトの動作では、すべての操作が確認なしで自動許可されます。 + +### 例: 厳格モード + +```json +{ + "permissions": { + "allow": ["read-in-cwd", "write-in-cwd", "query-git-log"], + "defaultMode": "askAll" + } +} +``` + +この設定では次のように動作します。 +- ワークスペース内の読み書きと Git 履歴の参照 → 自動許可 +- それ以外のすべての操作 → ユーザーの確認が必要 + +## 永続化 + +権限プロンプトで「Yes, and always allow」を選択すると、該当するスコープがプロジェクトの `.deepcode/settings.json` に書き込まれます。 + +- スコープは `permissions.allow` リストに追加されます +- そのスコープが以前 `deny` または `ask` に含まれていた場合は、自動的に削除されます +- 重複するスコープが二重に書き込まれることはありません + +これにより、同じスコープに関係する以降の呼び出しでは、確認プロンプトが表示されなくなります。 diff --git a/docs/quickstart_ja.md b/docs/quickstart_ja.md new file mode 100644 index 0000000..032ce92 --- /dev/null +++ b/docs/quickstart_ja.md @@ -0,0 +1,197 @@ +# クイックスタート + +Deep Code は、DeepSeek-V4 モデル向けのオープンソースのターミナル AI コーディングアシスタントです。深い思考(Thinking)と推論努力の制御に対応し、スキルや MCP(Model Context Protocol)によって機能を拡張できます。 + +## 前提条件 + +始める前に、以下を用意してください。 + +- Node.js `22` 以上 +- DeepSeek API キー + +## インストール + +npm で Deep Code をグローバルにインストールします。 + +```bash +npm install -g @vegamo/deepcode-cli +``` + +インストールされたバージョンを確認します。 + +```bash +deepcode --version +``` + +## DeepSeek-V4 の設定 + +Deep Code では `deepseek-v4-pro` を推奨しており、`deepseek-v4-flash` にも対応しています。`~/.deepcode/settings.json` を作成し、DeepSeek モデルの設定を追加してください。 + +```json +{ + "env": { + "MODEL": "deepseek-v4-pro", + "BASE_URL": "https://api.deepseek.com", + "API_KEY": "sk-..." + }, + "thinkingEnabled": true, + "reasoningEffort": "max" +} +``` + +`API_KEY` はお使いの DeepSeek API キーに置き換えてください。 + +主な項目: + +| 項目 | 説明 | +| ----- | ----------- | +| `env.MODEL` | DeepSeek のモデル名。`deepseek-v4-pro` を推奨 | +| `env.BASE_URL` | DeepSeek API のエンドポイント。デフォルトは `https://api.deepseek.com` | +| `env.API_KEY` | DeepSeek API キー | +| `thinkingEnabled` | 思考モードを有効にするかどうか | +| `reasoningEffort` | 推論努力。通常は `"high"` または `"max"` | + +プロジェクト内に `.deepcode/settings.json` を作成すれば、そのプロジェクトだけに適用されるモデル、権限、MCP の設定をカスタマイズすることもできます。 + +DeepSeek 公式のセットアップ手順については、[Deep Code 連携ガイド](https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/deepcode)を参照してください。 + +すべての設定オプションについては、[configuration_ja.md](configuration_ja.md) を参照してください。 + +## 起動 + +プロジェクトのディレクトリを開きます。 + +```bash +cd path/to/your/project +deepcode +``` + +Deep Code はカレントディレクトリで対話型のターミナル UI を起動します。タスクを入力して `Enter` を押してください。 + +初期プロンプトを指定して起動するには、次のようにします。 + +```bash +deepcode -p "Summarize this project" +``` + +## まず試してみる + +まずは読み取り専用のタスクから始めましょう。 + +```text +Summarize this repository and explain how to run it. +``` + +```text +Find the main entry points and explain the request flow. +``` + +次に、コーディングタスクを試してみます。 + +```text +Add a unit test for the login validation logic. +``` + +```text +Run the test suite and fix the failing tests. +``` + +先に計画を立ててもらうこともできます。 + +```text +Before editing files, propose a plan for adding pagination to the user list. +``` + +## 基本操作 + +| 操作 | キー | +| ------ | --- | +| メッセージを送信 | `Enter` | +| 改行を挿入 | `Shift+Enter` または `Ctrl+J` | +| 現在の応答を中断 | `Esc` | +| 画像を貼り付け | `Ctrl+V` | +| 終了 | `Ctrl+D` を 2 回押すか、`/exit` を使用 | + +## スラッシュコマンド + +入力欄に `/` と入力すると、コマンドメニューが開きます。 + +| コマンド | 動作 | +| ------- | ------ | +| `/new` | 新しい会話を開始する | +| `/resume` | 続きから再開する過去の会話を選ぶ | +| `/continue` | 現在の会話を続ける、または最新の会話を再開する | +| `/model` | モデル、思考モード、推論努力を切り替える | +| `/init` | 現在のプロジェクト用に `AGENTS.md` 指示ファイルを作成する | +| `/skills` | 利用可能なエージェントスキルを表示する | +| `/mcp` | MCP サーバーの状態と利用可能なツールを表示する | +| `/undo` | コードや会話を以前の時点に戻す | +| `/raw` | 表示モードを変更する | +| `/exit` | Deep Code を終了する | + +## プロジェクト指示の追加 + +プロジェクト内で次を実行します。 + +```text +/init +``` + +Deep Code が `AGENTS.md` の作成を手伝います。次のようなプロジェクトの約束事を記録しておきましょう。 + +- 依存関係のインストール方法とテストの実行方法 +- コードスタイルとコントリビューションの方針 +- 重要なディレクトリに関する注意事項 +- コード編集の前後に実行すべきチェック + +Deep Code は、そのプロジェクトで作業する際にこれらの指示を自動的に利用します。 + +## スキルを使う + +エージェントスキルは、コードレビュー、リリースチェック、ドキュメント生成、フレームワーク固有の開発手順など、再利用可能なワークフローです。 + +利用可能なスキルを一覧表示するには、次を実行します。 + +```text +/skills +``` + +`/` と入力してメニューからスキルを選ぶこともできます。 + +詳細は [agent-skills_ja.md](agent-skills_ja.md) を参照してください。 + +## 外部ツールとの連携 + +MCP を使うと、Deep Code を GitHub、ブラウザ、データベースなどのサービスに接続できます。 + +MCP を設定した後、次を実行します。 + +```text +/mcp +``` + +接続中の MCP サーバーと利用可能なツールが表示されます。 + +セットアップ手順は [mcp_ja.md](mcp_ja.md) を参照してください。 + +## 権限と安全性 + +Deep Code はファイルの読み取り、コードの編集、コマンドの実行を行うことがあります。どの操作を自動的に許可するか、どれを確認必須にするか、どれを拒否するかを設定できます。 + +Deep Code はデフォルトで YOLO モードに対応しており、ファイルの読み書きやコマンドの実行など、一般的なコーディングタスクをスムーズに進められます。より慎重に運用したい場合は、厳格な権限設定を使うことで、リスクの高い操作の前に Deep Code が確認を求めるようになります。 + +詳細は [permission_ja.md](permission_ja.md) を参照してください。 + +## タスク完了通知 + +Deep Code は、タスクの完了時に通知スクリプトを実行できます。たとえば Slack メッセージ、Feishu メッセージ、システム通知、ターミナルアラートの送信などです。 + +具体例は [notify_ja.md](notify_ja.md) を参照してください。 + +## 次のステップ + +- 設定ガイド全体を読む: [configuration_ja.md](configuration_ja.md) +- 権限を設定する: [permission_ja.md](permission_ja.md) +- エージェントスキルを書く: [agent-skills_ja.md](agent-skills_ja.md) +- MCP ツールを設定する: [mcp_ja.md](mcp_ja.md) +- タスク完了通知を設定する: [notify_ja.md](notify_ja.md) diff --git a/docs/session-persistence_ja.md b/docs/session-persistence_ja.md new file mode 100644 index 0000000..2d5a8fd --- /dev/null +++ b/docs/session-persistence_ja.md @@ -0,0 +1,139 @@ +# セッション永続化 + +Deep Code はプロジェクトごとのセッション履歴をローカルのユーザーディレクトリに保存します。この履歴は `/resume`、`/continue`、`/undo` の動作を支えており、現在のターミナルプロセスが終了した後も利用できます。 + +## 保存場所 + +各プロジェクトには専用の保存ディレクトリがあります。 + +```text +~/.deepcode/projects// +``` + +`` はプロジェクトのルートパスから生成されます。通常のパスは安全なディレクトリ名に変換されます。パスが長くなりすぎる場合、Deep Code はプロジェクト名の一部を残し、安定したハッシュを付加することで、保存パスの安全性を保ちます。 + +プロジェクトの保存ディレクトリには、主に次のファイルとディレクトリが含まれます。 + +| パス | 説明 | +| ---- | ----------- | +| `sessions-index.json` | 現在のプロジェクトのセッションインデックス。セッション一覧とサマリーのメタデータを含みます。 | +| `.jsonl` | 1 つのセッションのメッセージログ。各行が 1 件の JSON メッセージです。 | +| `file-history/.git` | `/undo` で復元されるコードチェックポイント用の内部 Git リポジトリです。 | + +## 永続化されるデータ + +### セッションインデックス + +`sessions-index.json` には最近のセッションエントリが保存されます。各エントリには次の情報が含まれます。 + +- セッション ID、タイトル、作成日時、更新日時。 +- セッションのステータス(`pending`、`processing`、`completed`、`failed`、`interrupted`、`ask_permission`、`waiting_for_user` など)。 +- 最新のアシスタントの返信、思考内容、拒否理由、失敗理由。 +- 最新のツール呼び出しデータ、トークン使用量、アクティブトークン数。 +- セッションが引き続き追跡しているサブプロセスのメタデータ。 + +セッションのデフォルトタイトルは、最初のユーザープロンプトの先頭 100 文字から生成されます。セッション一覧からセッション名を変更すると、インデックス内のタイトルが更新されます。 + +### メッセージファイル + +各セッションには `.jsonl` という名前の独立した JSONL メッセージファイルがあります。メッセージは順番に追記されます。主なフィールドは次のとおりです。 + +| フィールド | 説明 | +| ----- | ----------- | +| `id` | メッセージ ID。 | +| `sessionId` | 所属するセッションの ID。 | +| `role` | メッセージのロール: `system`、`user`、`assistant`、`tool` のいずれか。 | +| `content` | テキストコンテンツ。 | +| `contentParams` | 画像入力などの構造化コンテンツ。 | +| `messageParams` | ツール呼び出し ID、ツール呼び出し、推論コンテンツなどのモデルメッセージパラメータ。 | +| `visible` | メッセージを UI に表示するかどうか。 | +| `compacted` | 長時間セッションのコンパクションによってメッセージが置き換えられたかどうか。 | +| `checkpointHash` | `/undo` に関連付けられたコードチェックポイントのハッシュ。 | +| `meta` | ツール表示、スキル、権限、サマリーなどの関連機能のための追加メタデータ。 | + +メッセージファイルの読み込み時、Deep Code は JSON を 1 行ずつ解析します。不正な形式の行は無視されるため、残りの利用可能な履歴は引き続き読み込めます。 + +### コードチェックポイント + +Deep Code はコードチェックポイントを `file-history/.git` に保存します。このリポジトリは内部的なファイル履歴専用であり、プロジェクトの Git リポジトリではありません。 + +- 新しいセッションは、セッション ID を名前とする内部ブランチを初期化します。 +- 各ユーザープロンプトの前に、Deep Code はすでに追跡しているファイルの状態を記録します。 +- ツールによるファイル変更の前後に、Deep Code は必要に応じて対象ファイルの状態を記録します。 +- ユーザーメッセージ上の `checkpointHash` が、会話上の位置とコードの状態を結び付けます。 + +チェックポイントの対象は、Deep Code が追跡しているファイルのみです。無関係なファイルが `/undo` によって勝手に書き換えられることはありません。 + +## セッションのライフサイクル + +### セッションの作成 + +新しいセッションを作成するとき、Deep Code は次の処理を行います。 + +1. 新しいセッション ID を生成します。 +2. そのセッション用のコードチェックポイントブランチを初期化します。 +3. `sessions-index.json` にエントリを追加します。 +4. システムプロンプト、実行時コンテキスト、プロジェクト指示、ユーザーメッセージを書き込みます。 +5. モデルへのリクエストを開始し、アシスタントの返信やツール実行が完了するたびに、インデックスとメッセージファイルを更新し続けます。 + +プロジェクトごとのセッション一覧には、直近の 50 件のエントリが保持されます。上限を超えると、古いセッションはインデックスから削除され、そのメッセージファイルと関連する実行時リソースがクリーンアップされます。 + +### セッションの継続 + +`/resume` は現在のプロジェクトのセッション履歴を表示し、継続するセッションを選択できるようにします。 + +`/continue` はまずアクティブなセッションを継続します。継続できるアクティブなセッションがない場合は、セッション選択のフローを開きます。 + +セッションを継続するとき、Deep Code はメッセージファイルを読み込み、コンパクションされた古いメッセージをフィルタリングし、不完全なツール呼び出しコンテキストを修復したうえで、利用可能な履歴をモデルリクエスト用のメッセージに変換します。 + +### 長時間セッションのコンパクション + +会話のコンテキストが大きくなりすぎた場合、Deep Code は過去のメッセージをコンパクション(圧縮)できます。 + +- 古い範囲の非システムメッセージを要約します。 +- 対象の古いメッセージに `compacted: true` のマークを付けます。 +- メッセージシーケンスに、非表示のシステム要約メッセージを挿入します。 + +以降のリクエストでは、残りのアクティブなメッセージと要約メッセージが使用されます。元のメッセージは監査可能性と UI 上の履歴表示のために JSONL ファイルに残ります。 + +### 中断・失敗・権限待ち + +実行中にセッションのステータスは次のように変化します。 + +- ユーザーによる中断の後、ステータスは `interrupted` になり、Deep Code は現在のセッションコントローラと追跡中のサブプロセスをクリアします。 +- リクエストの失敗の後、ステータスは `failed` になり、失敗理由がインデックスに書き込まれます。 +- ツール呼び出しに確認が必要な場合、ステータスは `ask_permission` になります。 +- ツールがユーザー入力を必要とする場合、ステータスは `waiting_for_user` になります。 + +これらの状態は `sessions-index.json` に永続化されるため、CLI を再度開いた後もセッション一覧で確認できます。 + +## `/undo` による永続化データの利用 + +`/undo` の候補は、表示されておりコンパクションされていないユーザーメッセージから選ばれます。各候補について、関連付けられた `checkpointHash` の有無が確認され、Deep Code はそのチェックポイントが復元可能かどうかを検証します。 + +選択したモードに応じて、Deep Code は次の操作を実行できます。 + +| 操作 | 動作 | +| --------- | -------- | +| 会話の復元 | 選択したユーザーメッセージより前でメッセージ履歴を切り詰め、インデックス内の最新のアシスタントデータを更新します。 | +| コードの復元 | `file-history/.git` から選択したチェックポイントを読み込み、追跡対象のファイルを復元します。 | +| 両方の復元 | まずコードを復元し、その後に会話履歴を切り詰めます。 | + +会話の復元はセッションの JSONL ファイルを書き換えます。コードの復元は、選択したチェックポイントが追跡しているワークスペースのファイルを変更します。 + +## 削除と名前変更 + +セッション一覧からセッションを削除すると、次の処理が行われます。 + +- `sessions-index.json` からエントリを削除します。 +- 対応する `.jsonl` ファイルを削除します。 +- そのセッションのメモリ上の状態、一時的な作業ディレクトリの状態、コントローラ、追跡中のプロセス制御をクリアします。 + +セッションの名前変更は、インデックス内の `summary` フィールドのみを更新します。メッセージファイルやコードチェックポイントは変更されません。 + +## 補足 + +- セッションデータはローカルのユーザーディレクトリに保存され、プロジェクトごとに分離されています。 +- プロジェクトディレクトリを移動すると、新しいプロジェクトルートパスから新しい `` が生成されます。移動前のパスの履歴が自動的に移行されることはありません。 +- `file-history/.git` は Deep Code の内部チェックポイントリポジトリであり、手動で編集しないでください。 +- セッションを削除しても、内部 Git リポジトリからすべての履歴オブジェクトが削除されるわけではありません。主に削除されるのは、セッションインデックスのエントリ、メッセージファイル、実行時リソースです。 diff --git a/docs/statusline_ja.md b/docs/statusline_ja.md new file mode 100644 index 0000000..cc16094 --- /dev/null +++ b/docs/statusline_ja.md @@ -0,0 +1,149 @@ +# ステータスラインプラグイン + +Deep Code CLI では、CLI のソースコードを変更することなく、プラグインを通じてターミナル下部のステータスラインにカスタム情報(Git ブランチ、現在時刻、トークン使用量など)を表示できます。ステータスラインはプロンプト入力欄の下にあるキーボードヒント行のさらに下に描画され、すべてのプロバイダーの出力がセパレーターで連結されて表示されます。 + +## 設定 + +`~/.deepcode/settings.json`(またはプロジェクトレベルの `.deepcode/settings.json`)に `statusline` フィールドを追加します。 + +```json +{ + "statusline": { + "enabled": true, + "refreshMs": 2000, + "separator": " · ", + "providers": [ + { + "type": "command", + "id": "git", + "command": "git branch --show-current", + "color": "cyan" + }, + { + "type": "module", + "id": "tokens", + "path": "./.deepcode/plugins/tokens.mjs", + "color": "yellow" + } + ] + } +} +``` + +### フィールド + +| フィールド | 型 | 説明 | +| ------------- | --------- | ---------------------------------------------------------------------------- | +| `enabled` | boolean | ステータスラインを有効にするかどうか。省略した場合、プロバイダーが 1 つ以上設定されていればデフォルトで true になります。 | +| `refreshMs` | number | 更新間隔(ミリ秒)。最小値は 500、デフォルトは 2000 です。 | +| `separator` | string | プロバイダー出力間のセパレーター。デフォルトは `" · "` です。 | +| `providers` | array | プロバイダーのリスト。宣言順に描画されます。 | + +## プロバイダーの種類 + +### `command` — 外部コマンドの実行 + +`refreshMs` ごとにシェルコマンドを実行し、標準出力の最初の行をステータスセグメントとして使用します。 + +| フィールド | 型 | 必須 | 説明 | +| ----------- | ------- | -------- | ------------------------------------------------------------------------ | +| `type` | string | はい | `"command"` を指定します。 | +| `command` | string | はい | シェルコマンド(パイプやリダイレクトなどにも対応)。 | +| `id` | string | いいえ | 一意の識別子。省略した場合はインデックスから自動生成されます。 | +| `cwd` | string | いいえ | 作業ディレクトリ。相対パスはプロジェクトルートを基準に解決されます。 | +| `timeoutMs` | number | いいえ | タイムアウト(ミリ秒)。デフォルトは 1500。タイムアウト時は空文字列になります。 | +| `color` | string | いいえ | Ink がサポートする色(例: `"red"`、`"#229ac3"`)。 | + +例: + +```json +{ "type": "command", "id": "git", "command": "git status -sb | head -1" } +{ "type": "command", "id": "time", "command": "date +%H:%M" } +{ "type": "command", "id": "node", "command": "node -v", "color": "green" } +``` + +### `module` — JS モジュールの読み込み + +ローカルの JS/MJS モジュールを読み込み、デフォルトエクスポートされた関数を呼び出します。その戻り値がセグメントのテキストになります。 + +| フィールド | 型 | 必須 | 説明 | +| ----------- | ------- | -------- | ------------------------------------------------------------------------------------ | +| `type` | string | はい | `"module"` を指定します。 | +| `path` | string | はい | モジュールのパス。相対パスはプロジェクトルートを基準に解決されます。 | +| `id` | string | いいえ | 一意の識別子。 | +| `timeoutMs` | number | いいえ | タイムアウト(ミリ秒)。デフォルトは 2000。 | +| `color` | string | いいえ | Ink がサポートする色。 | + +モジュールは `default` 関数(または `provider` という名前付きエクスポート)をエクスポートする必要があります。 + +```js +// .deepcode/plugins/tokens.mjs +export default function tokensProvider({ projectRoot, session }) { + // 文字列を返します(同期・非同期のどちらでも可)。 + if (session?.activeSessionId) { + return `msgs:${session.messageCount} reqs:${session.requestCount} tokens:${session.totalTokens}`; + } + return `tokens: 1.2k`; +} +``` + +この関数は `{ projectRoot: string, session: SessionInfo | null }` を受け取り、`string` または `Promise` を返します。 + +`SessionInfo` の構造: + +| フィールド | 型 | 説明 | +| ----------------- | ------------------- | ---------------------------------------------------------- | +| `activeSessionId` | `string \| null` | 現在アクティブなセッションの ID。存在しない場合は `null`。 | +| `messageCount` | `number` | アクティブなセッション内のメッセージ総数。 | +| `requestCount` | `number` | アクティブなセッションで実行された LLM API リクエストの総数。 | +| `totalTokens` | `number` | アクティブなセッションで消費されたトークンの総数。 | + +## 安全上の制約 + +- **モジュールプロバイダーのパスは、プロジェクトルートまたはユーザーのホームディレクトリの配下に置く必要があります**。どちらの外にもある絶対パスは拒否されます(任意のコードの読み込みを防ぐため)。 +- 各セグメントのテキストには自動的に次の処理が適用されます: + - 最初の空でない行のみに切り詰め + - ANSI エスケープシーケンスの除去 + - 連続する空白の圧縮 + - 40 文字への切り詰め(超過分は `…` で表示) +- コマンドプロバイダーの標準出力は 4 KB までに制限されます。 +- いずれかのプロバイダーが例外を投げた場合、タイムアウトした場合、または空文字列を返した場合は、**そのセグメントだけがスキップされ**、他のセグメントには影響しません。 + +## 動作 + +- 最初の更新は CLI の起動直後に実行され、その後は設定された間隔で実行されます。 +- ユーザーレベル設定とプロジェクトレベル設定の `providers` 配列は**マージ**されます(ユーザー設定が先、プロジェクト設定が後)。その他のフィールドはプロジェクトレベルの値が優先されます。 +- ステータスラインはあらゆる状態(処理中や権限プロンプトの表示中を含む)で表示され、処理中インジケーターの妨げにはなりません。 +- 設定の変更を反映するには CLI の再起動が必要です(ホットリロードには対応していません)。 + +## 完全な設定例 + +```json +{ + "statusline": { + "enabled": true, + "refreshMs": 3000, + "providers": [ + { + "type": "command", + "id": "branch", + "command": "git branch --show-current", + "color": "cyan" + }, + { + "type": "command", + "id": "dirty", + "command": "git status --porcelain | wc -l | xargs -I{} echo '{} files changed'", + "color": "yellow" + }, + { + "type": "module", + "id": "ts-errors", + "path": "./.deepcode/plugins/ts-errors.mjs", + "color": "red", + "timeoutMs": 5000 + } + ] + } +} +```