@quolu/aishell 0.3.1 → 0.3.3
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/LICENSE +202 -0
- package/README.ja.md +165 -0
- package/README.md +126 -50
- package/dist/AIShell.app/Contents/Helpers/aishell-mcp +0 -0
- package/dist/AIShell.app/Contents/Info.plist +2 -2
- package/dist/AIShell.app/Contents/MacOS/AIShell +0 -0
- package/dist/AIShell.app/Contents/_CodeSignature/CodeResources +2 -2
- package/package.json +2 -2
package/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
package/README.ja.md
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src=".github/og.png" alt="AIShell — AI開発へDirect OS contextを提供" width="100%">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# AIShell
|
|
6
|
+
|
|
7
|
+
[](https://github.com/kitepon-rgb/aishell/actions/workflows/ci.yml)
|
|
8
|
+
[](https://www.npmjs.com/package/@quolu/aishell)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
> AI開発hostへfreshなworkspace state、budget付きcontext、保持された実行証拠を渡すmacOS-native MCP runtime。すべての操作をshell文字列へ潰さず、OSに面する状態をモデルより下で所有する。
|
|
13
|
+
|
|
14
|
+
[English](README.md)
|
|
15
|
+
|
|
16
|
+
AIShellは許可root、file identity、filesystem照合state、直接起動したprocess、完全log、artifactを所有する。reasoning、thread、compaction、sub-agent、汎用terminalはAI hostの責務として残す。
|
|
17
|
+
|
|
18
|
+
## 30秒で試す
|
|
19
|
+
|
|
20
|
+
Apple Silicon Mac、macOS 15以降が必要。
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
npm install -g @quolu/aishell
|
|
24
|
+
aishell-open
|
|
25
|
+
codex mcp add aishell -- /opt/homebrew/bin/aishell-mcp
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
管理アプリでAIに許可するfolderを追加し、新しいCodex taskで次のように頼む。
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
初回workspace contextはworkspace_snapshotで取得して。focused testはrun_checkで実行し、
|
|
32
|
+
summaryから省略された証拠だけartifact_readで読んで。
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
既定profileは5本の高密度development toolと、常時利用できる2本の復旧control toolを提供する。
|
|
36
|
+
|
|
37
|
+
| Tool | 役割 |
|
|
38
|
+
|---|---|
|
|
39
|
+
| `workspace_snapshot` | boundedな初回preview、照合済み変更delta、Git状態、主要context |
|
|
40
|
+
| `read_context` | SHA-256 identityとcontinuationを持つbudget付き複数file read |
|
|
41
|
+
| `search_context` | 直接起動した`rg` workerによるbudget付き検索context |
|
|
42
|
+
| `run_check` | 直接process実行、主要diagnostic、完全stdout/stderr artifact |
|
|
43
|
+
| `artifact_read` | 保持artifactのrange、tail、pattern周辺read |
|
|
44
|
+
| `runtime_status` | 未設定・停止中も含む許可root、停止、worktree、次操作の状態取得 |
|
|
45
|
+
| `runtime_open_manager` | root追加またはAI操作再開のため管理アプリを開く |
|
|
46
|
+
|
|
47
|
+
## なぜAIShellか
|
|
48
|
+
|
|
49
|
+
statelessな連携では、モデルがworkspaceを何度もscanし、command出力から状態を再構成しやすい。AIShellは状態を持つOS側の仕事をモデルより下へ置き、後続turnが全再scanではなくdeltaと一次証拠を要求できるようにする。
|
|
50
|
+
|
|
51
|
+
| 論点 | AIShell | 一般的なshell-first連携 |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| Workspace state | file identity＋filesystem観測と照合 | commandを再実行してtextから再構成 |
|
|
54
|
+
| Context | budget・cursor付きstructured result | stdoutを手動または暗黙に切り詰める |
|
|
55
|
+
| Execution | executable URL、引数、cwd、lifecycleを分離 | shellが1本のcommand文字列を評価 |
|
|
56
|
+
| Evidence | 完全stdout/stderrを期限付きhandleで保持 | response truncation時に証拠が失われやすい |
|
|
57
|
+
| Scope | 人が管理する許可rootと明示的stop状態 | 周囲のshellとhost policyに依存 |
|
|
58
|
+
|
|
59
|
+
AIShellはsandboxではなく、任意code実行を安全化しない。process railの目的はtyped executionと観測可能なlifecycleを維持することであり、改名binaryや許可workerが起動する子processを阻止することではない。
|
|
60
|
+
|
|
61
|
+
## Architecture
|
|
62
|
+
|
|
63
|
+
```mermaid
|
|
64
|
+
flowchart LR
|
|
65
|
+
Host[AI host<br/>reasoning · threads · compaction] --> MCP[AIShellMCP<br/>MCP 2025-11-25]
|
|
66
|
+
MCP --> Core[AIShellCore]
|
|
67
|
+
Core --> State[Allowed roots · file identity<br/>FSEvents + reconciliation]
|
|
68
|
+
Core --> Process[Direct process lifecycle<br/>stdout · stderr · timeout]
|
|
69
|
+
Core --> Evidence[Retained evidence<br/>artifacts · freshness]
|
|
70
|
+
Process --> Workers[git · rg · compiler · tests]
|
|
71
|
+
State --> macOS[macOS APIs]
|
|
72
|
+
Evidence --> Host
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`AIShellCore`がdomain挙動を所有し、`AIShellMCP`はprotocol request/resultだけを変換する。Git、ripgrep、compiler、test、SourceKit-LSPは新しいstate ownerにせず、直接起動するworkerとして再利用する。
|
|
76
|
+
|
|
77
|
+
## npmからinstall
|
|
78
|
+
|
|
79
|
+
global packageは`aishell-mcp`と`aishell-open`を`PATH`へ追加する。`aishell-open`は同梱された管理アプリをLaunchServicesで開く。install scriptは実行しない。
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
npm install -g @quolu/aishell
|
|
83
|
+
aishell-open
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
現在の実験版はDeveloper ID署名・notarization前である。
|
|
87
|
+
|
|
88
|
+
## Sourceからbuild
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
git clone https://github.com/kitepon-rgb/aishell.git
|
|
92
|
+
cd aishell
|
|
93
|
+
swift test
|
|
94
|
+
scripts/package-app.sh release
|
|
95
|
+
open build/AIShell.app
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
MCP実行ファイルは`build/AIShell.app/Contents/Helpers/aishell-mcp`へ同梱される。
|
|
99
|
+
|
|
100
|
+
管理アプリの「許可rootを追加」でAIに操作させるfolderを選ぶ。許可済みGit repositoryの`.git/worktrees`へ正式登録され、双方の管理情報が一致するworktreeは自動的に実効rootへ加わる。
|
|
101
|
+
|
|
102
|
+
## 別のAI hostへ接続
|
|
103
|
+
|
|
104
|
+
Homebrew prefixへnpm installした場合は絶対pathを登録する。
|
|
105
|
+
|
|
106
|
+
```sh
|
|
107
|
+
codex mcp add aishell -- /opt/homebrew/bin/aishell-mcp
|
|
108
|
+
codex mcp get aishell
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
解除:
|
|
112
|
+
|
|
113
|
+
```sh
|
|
114
|
+
codex mcp remove aishell
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
互換用full profileは全25 toolを提供する。既定7本は5本のdevelopment toolと2本の復旧control toolで、full modeは残りのlegacy primitiveも公開する。
|
|
118
|
+
|
|
119
|
+
```sh
|
|
120
|
+
AISHELL_TOOL_PROFILE=full /opt/homebrew/bin/aishell-mcp
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
full profileにはfile一覧・read、SHA-256競合検出付きatomic update、copy/move/rename/Trash、直接process実行、app discovery/launch、runtime status、管理アプリの前面化が含まれる。
|
|
124
|
+
|
|
125
|
+
## 実行と安全性の境界
|
|
126
|
+
|
|
127
|
+
- shell command文字列を評価しない。開発programを`PATH`からexecutable URLへ解決し、arguments、environment、working directoryと分離する。
|
|
128
|
+
- `sh`、`bash`、`zsh`、`env`、`osascript`等のbasename直接起動を製品上のrailとして拒否する。security boundaryとして宣伝しない。
|
|
129
|
+
- `run_check`はopen-world capabilityであり、許可workerはfile更新・子process・network accessを行い得る。AI hostによっては実行承認が必要になる。
|
|
130
|
+
- text更新はSHA-256または旧textを事前条件にできる。削除はTrashへ送る。
|
|
131
|
+
- 管理アプリから通常操作を一括停止できる。停止中もruntime statusと管理アプリの前面化は利用できる。
|
|
132
|
+
|
|
133
|
+
## 現在の制限
|
|
134
|
+
|
|
135
|
+
- stdio serverは1 requestずつ処理する。
|
|
136
|
+
- MCP cancellationと並列run pollingは未実装。
|
|
137
|
+
- timeout時は直接所有するprocess treeを終了するが、終了までに許可workerがopen-worldな副作用を起こし得る。
|
|
138
|
+
- 初回workspace entryはbounded previewで、後続deltaはcursor pageになる。
|
|
139
|
+
- Developer ID署名とnotarizationは未設定。
|
|
140
|
+
|
|
141
|
+
## 開発検証
|
|
142
|
+
|
|
143
|
+
```sh
|
|
144
|
+
swift test
|
|
145
|
+
scripts/package-app.sh release
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`xcodegen generate`で`AIShell.xcodeproj`を再生成できる。実装の正本は`Sources/AIShellCore`、`Sources/AIShellMCP`、`Sources/AIShellApp`、focused testは`Tests/`に置く。
|
|
149
|
+
|
|
150
|
+
<details>
|
|
151
|
+
<summary>ローカルXcode検証時の注記</summary>
|
|
152
|
+
|
|
153
|
+
初回検証機ではXcode 26.6とCoreSimulatorのbuild versionが一致せず、`xcodebuild`はXCBuild開始前に停止した。同じSwift 6.3.3 toolchainを使うSwiftPMは通過した。このhost問題はsourceの成功扱いへ混ぜていない。
|
|
154
|
+
|
|
155
|
+
</details>
|
|
156
|
+
|
|
157
|
+
## ContributionとSecurity
|
|
158
|
+
|
|
159
|
+
変更提案前に[CONTRIBUTING.md](CONTRIBUTING.md)を確認してほしい。脆弱性はpublic issueへ書かず、[SECURITY.md](SECURITY.md)のprivate経路で報告する。
|
|
160
|
+
|
|
161
|
+
release notesは[`docs/`](docs/)に置き、GitHub Releasesを公開済みversionの正本とする。
|
|
162
|
+
|
|
163
|
+
## License
|
|
164
|
+
|
|
165
|
+
AIShellは[Apache License 2.0](LICENSE)で公開している。
|
package/README.md
CHANGED
|
@@ -1,89 +1,165 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src=".github/og.png" alt="AIShell — Direct OS context for AI development" width="100%">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
1
5
|
# AIShell
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
[](https://github.com/kitepon-rgb/aishell/actions/workflows/ci.yml)
|
|
8
|
+
[](https://www.npmjs.com/package/@quolu/aishell)
|
|
9
|
+
|
|
10
|
+
|
|
4
11
|
|
|
5
|
-
|
|
12
|
+
> A macOS-native MCP runtime that gives AI development hosts fresh workspace state, bounded context, and retained execution evidence—without collapsing every operation into a shell string.
|
|
6
13
|
|
|
7
|
-
|
|
8
|
-
- `workspace_snapshot`: 初回scanのbounded previewとFSEvents由来の変更delta、Git状態、主要context
|
|
9
|
-
- `read_context`: 複数fileのbudget付きread、SHA-256、continuation
|
|
10
|
-
- `search_context`: `rg` workerによるbudget付き検索context
|
|
11
|
-
- `run_check`: 直接process実行、主要診断、完全stdout/stderr artifact
|
|
12
|
-
- `artifact_read`: artifactのrange、tail、pattern周辺read
|
|
13
|
-
- 許可フォルダ内の一覧、検索、UTF-8テキスト読取
|
|
14
|
-
- フォルダ／テキスト作成、copy、move、rename、Trash
|
|
15
|
-
- stat、SHA-256、再帰tree
|
|
16
|
-
- SHA-256競合検出付き原子的更新、旧テキストを事前条件にした部分置換
|
|
17
|
-
- executable URLと引数配列による開発プログラムの直接実行
|
|
18
|
-
- working directory、環境変数、timeout、stdout、stderr、終了コードの取得
|
|
19
|
-
- 実行中／インストール済みアプリの一覧
|
|
20
|
-
- bundle identifierによるアプリ起動・前面化
|
|
21
|
-
- 管理アプリから複数の許可rootを追加・削除、全停止、操作履歴確認
|
|
22
|
-
- 停止中でも状態確認と管理アプリ起動が可能
|
|
23
|
-
- 許可済みGitリポジトリに登録されたworktreeを追加操作なしで自動認識
|
|
24
|
-
- MCP 2025-11-25 stdio接続
|
|
14
|
+
[日本語](README.ja.md)
|
|
25
15
|
|
|
26
|
-
|
|
16
|
+
AIShell owns the OS-facing state below the model: allowed roots, file identity, filesystem reconciliation, directly launched processes, complete logs, and retained artifacts. The AI host remains responsible for reasoning, threads, compaction, sub-agents, and general-purpose terminal work.
|
|
27
17
|
|
|
28
|
-
|
|
18
|
+
## Try it in 30 seconds
|
|
29
19
|
|
|
30
|
-
|
|
20
|
+
Requires an Apple Silicon Mac running macOS 15 or later.
|
|
31
21
|
|
|
32
|
-
```
|
|
22
|
+
```sh
|
|
33
23
|
npm install -g @quolu/aishell
|
|
34
24
|
aishell-open
|
|
25
|
+
codex mcp add aishell -- /opt/homebrew/bin/aishell-mcp
|
|
35
26
|
```
|
|
36
27
|
|
|
37
|
-
|
|
28
|
+
In the manager app, add the folders the AI may access. Start a new Codex task and try:
|
|
38
29
|
|
|
39
|
-
|
|
30
|
+
```text
|
|
31
|
+
Use workspace_snapshot for the initial workspace context. Run the focused tests with
|
|
32
|
+
run_check, and read retained output with artifact_read only if the summary omits evidence.
|
|
33
|
+
```
|
|
40
34
|
|
|
41
|
-
|
|
35
|
+
The default profile exposes five high-density development tools plus two always-available recovery controls:
|
|
36
|
+
|
|
37
|
+
| Tool | Purpose |
|
|
38
|
+
|---|---|
|
|
39
|
+
| `workspace_snapshot` | Bounded initial workspace preview, reconciled change delta, Git state, and primary context |
|
|
40
|
+
| `read_context` | Budgeted multi-file reads with SHA-256 identity and continuation |
|
|
41
|
+
| `search_context` | Budgeted search context produced by a directly launched `rg` worker |
|
|
42
|
+
| `run_check` | Direct process execution, primary diagnostics, and complete stdout/stderr artifacts |
|
|
43
|
+
| `artifact_read` | Range, tail, and pattern-centered reads from retained artifacts |
|
|
44
|
+
| `runtime_status` | Allowed-root, pause, worktree, and next-action state, including while paused or unconfigured |
|
|
45
|
+
| `runtime_open_manager` | Open the manager app to add roots or resume AI operations |
|
|
46
|
+
|
|
47
|
+
## Why AIShell
|
|
48
|
+
|
|
49
|
+
Typical stateless integrations repeatedly ask the model to rediscover workspace state and interpret command output. AIShell keeps the stateful, OS-facing part below the model so later turns can ask for deltas and primary evidence instead of rescanning everything.
|
|
50
|
+
|
|
51
|
+
| Concern | AIShell | Typical shell-first integration |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| Workspace state | File identity plus filesystem observation and reconciliation | Re-run commands and reconstruct state from text |
|
|
54
|
+
| Context | Bounded, cursor-based structured results | Unbounded or manually truncated stdout |
|
|
55
|
+
| Execution | Executable URL, arguments, working directory, and lifecycle remain separate | A shell evaluates one command string |
|
|
56
|
+
| Evidence | Complete stdout/stderr retained behind expiring handles | Evidence often disappears when the response is truncated |
|
|
57
|
+
| Scope | Human-managed allowed roots and explicit stop state | Depends on the surrounding shell and host policy |
|
|
58
|
+
|
|
59
|
+
AIShell is not a sandbox and does not make arbitrary code execution safe. Its process rails exist to preserve typed execution and observable lifecycle—not to stop renamed binaries or child processes launched by an allowed worker.
|
|
60
|
+
|
|
61
|
+
## Architecture
|
|
62
|
+
|
|
63
|
+
```mermaid
|
|
64
|
+
flowchart LR
|
|
65
|
+
Host[AI host<br/>reasoning · threads · compaction] --> MCP[AIShellMCP<br/>MCP 2025-11-25]
|
|
66
|
+
MCP --> Core[AIShellCore]
|
|
67
|
+
Core --> State[Allowed roots · file identity<br/>FSEvents + reconciliation]
|
|
68
|
+
Core --> Process[Direct process lifecycle<br/>stdout · stderr · timeout]
|
|
69
|
+
Core --> Evidence[Retained evidence<br/>artifacts · freshness]
|
|
70
|
+
Process --> Workers[git · rg · compiler · tests]
|
|
71
|
+
State --> macOS[macOS APIs]
|
|
72
|
+
Evidence --> Host
|
|
73
|
+
```
|
|
42
74
|
|
|
43
|
-
|
|
75
|
+
`AIShellCore` owns domain behavior. `AIShellMCP` only translates protocol requests and results. Git, ripgrep, compilers, tests, and SourceKit-LSP remain directly launched workers rather than becoming new state owners.
|
|
44
76
|
|
|
45
|
-
|
|
77
|
+
## Install from npm
|
|
46
78
|
|
|
47
|
-
|
|
48
|
-
|
|
79
|
+
The global package adds `aishell-mcp` and `aishell-open` to `PATH`. `aishell-open` opens the bundled manager app through LaunchServices. The package runs no install script.
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
npm install -g @quolu/aishell
|
|
83
|
+
aishell-open
|
|
49
84
|
```
|
|
50
85
|
|
|
51
|
-
|
|
86
|
+
The current experimental build is not yet Developer ID signed or notarized.
|
|
52
87
|
|
|
53
|
-
|
|
88
|
+
## Build from source
|
|
54
89
|
|
|
55
|
-
```
|
|
56
|
-
|
|
90
|
+
```sh
|
|
91
|
+
git clone https://github.com/kitepon-rgb/aishell.git
|
|
92
|
+
cd aishell
|
|
93
|
+
swift test
|
|
94
|
+
scripts/package-app.sh release
|
|
95
|
+
open build/AIShell.app
|
|
57
96
|
```
|
|
58
97
|
|
|
59
|
-
|
|
98
|
+
The MCP executable is bundled at `build/AIShell.app/Contents/Helpers/aishell-mcp`.
|
|
60
99
|
|
|
61
|
-
|
|
62
|
-
複数file・反復workspace観測ではworkspace_snapshotを使い、返されたcursorでdeltaを取って。32 KiBを超え得るbuild/test出力はrun_checkを使い、通常responseにない証拠だけartifact_readで読む。小さな単一file作業はCodex標準toolを使ってよい。
|
|
63
|
-
```
|
|
100
|
+
After opening the app, use **Add Allowed Root** to select the folders AIShell may access. A Git worktree registered under an allowed repository is recognized automatically when both sides of the worktree metadata agree.
|
|
64
101
|
|
|
65
|
-
|
|
102
|
+
## Connect another AI host
|
|
66
103
|
|
|
67
|
-
|
|
104
|
+
For a Homebrew-prefix npm installation, register the absolute executable path:
|
|
68
105
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
```text
|
|
106
|
+
```sh
|
|
107
|
+
codex mcp add aishell -- /opt/homebrew/bin/aishell-mcp
|
|
72
108
|
codex mcp get aishell
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Remove the registration with:
|
|
112
|
+
|
|
113
|
+
```sh
|
|
73
114
|
codex mcp remove aishell
|
|
74
115
|
```
|
|
75
116
|
|
|
76
|
-
|
|
117
|
+
The compatibility profile retains all 25 tools. The default seven are the five development tools plus the two recovery controls; full mode adds the remaining legacy primitives:
|
|
77
118
|
|
|
78
|
-
```
|
|
119
|
+
```sh
|
|
120
|
+
AISHELL_TOOL_PROFILE=full /opt/homebrew/bin/aishell-mcp
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The full profile includes file listing and reads, atomic SHA-256-guarded updates, copy/move/rename/Trash, direct process execution, app discovery and launch, runtime status, and manager activation.
|
|
124
|
+
|
|
125
|
+
## Execution and safety boundaries
|
|
126
|
+
|
|
127
|
+
- AIShell never evaluates a shell command string. It resolves a development program from `PATH` to an executable URL and keeps arguments, environment, and working directory separate.
|
|
128
|
+
- Direct launch of shell and wrapper basenames such as `sh`, `bash`, `zsh`, `env`, and `osascript` is rejected as a product rail, not advertised as a security boundary.
|
|
129
|
+
- `run_check` is an open-world capability: an allowed worker may update files, launch child processes, or access the network. AI hosts may require approval before execution.
|
|
130
|
+
- Text updates may use SHA-256 or expected old text as a precondition. Deletes go to Trash.
|
|
131
|
+
- The manager app can stop normal operations globally. Runtime status and manager activation remain available while stopped.
|
|
132
|
+
|
|
133
|
+
## Current limitations
|
|
134
|
+
|
|
135
|
+
- The stdio server handles one request at a time.
|
|
136
|
+
- MCP cancellation and concurrent run polling are not implemented.
|
|
137
|
+
- A timeout terminates the directly owned process tree, but an allowed worker remains capable of open-world side effects before termination.
|
|
138
|
+
- Initial workspace entries are a bounded preview; later deltas are cursor-paged.
|
|
139
|
+
- Developer ID signing and notarization are not yet configured.
|
|
140
|
+
|
|
141
|
+
## Development
|
|
142
|
+
|
|
143
|
+
```sh
|
|
79
144
|
swift test
|
|
80
145
|
scripts/package-app.sh release
|
|
81
146
|
```
|
|
82
147
|
|
|
83
|
-
`xcodegen generate`
|
|
148
|
+
Run `xcodegen generate` to regenerate `AIShell.xcodeproj`. The authoritative implementation lives under `Sources/AIShellCore`, `Sources/AIShellMCP`, and `Sources/AIShellApp`; focused tests live under `Tests/`.
|
|
149
|
+
|
|
150
|
+
<details>
|
|
151
|
+
<summary>Local Xcode verification note</summary>
|
|
152
|
+
|
|
153
|
+
On the original verification machine, Xcode 26.6 and the installed CoreSimulator build version did not match, so `xcodebuild` stalled before XCBuild began. The same Swift 6.3.3 toolchain passed through SwiftPM. That host issue was not counted as source success.
|
|
154
|
+
|
|
155
|
+
</details>
|
|
156
|
+
|
|
157
|
+
## Contributing and security
|
|
158
|
+
|
|
159
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change. Please report vulnerabilities through the private process in [SECURITY.md](SECURITY.md), not through a public issue.
|
|
84
160
|
|
|
85
|
-
|
|
161
|
+
Release notes are kept in [`docs/`](docs/). GitHub Releases are the public record for shipped versions.
|
|
86
162
|
|
|
87
|
-
|
|
163
|
+
## License
|
|
88
164
|
|
|
89
|
-
|
|
165
|
+
AIShell is licensed under the [Apache License 2.0](LICENSE).
|
|
Binary file
|
|
@@ -17,9 +17,9 @@
|
|
|
17
17
|
<key>CFBundlePackageType</key>
|
|
18
18
|
<string>APPL</string>
|
|
19
19
|
<key>CFBundleShortVersionString</key>
|
|
20
|
-
<string>0.3.
|
|
20
|
+
<string>0.3.3</string>
|
|
21
21
|
<key>CFBundleVersion</key>
|
|
22
|
-
<string>
|
|
22
|
+
<string>7</string>
|
|
23
23
|
<key>LSApplicationCategoryType</key>
|
|
24
24
|
<string>public.app-category.utilities</string>
|
|
25
25
|
<key>LSMinimumSystemVersion</key>
|
|
Binary file
|
|
@@ -10,10 +10,10 @@
|
|
|
10
10
|
<dict>
|
|
11
11
|
<key>cdhash</key>
|
|
12
12
|
<data>
|
|
13
|
-
|
|
13
|
+
7xZ0nBtAcU2VykKqtpKSvPwhR0c=
|
|
14
14
|
</data>
|
|
15
15
|
<key>requirement</key>
|
|
16
|
-
<string>cdhash H"
|
|
16
|
+
<string>cdhash H"ef16749c1b40714d95ca42aab69292bcfc214747"</string>
|
|
17
17
|
</dict>
|
|
18
18
|
</dict>
|
|
19
19
|
<key>rules</key>
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quolu/aishell",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.3",
|
|
4
4
|
"description": "A native macOS state runtime with high-density MCP tools for AI development",
|
|
5
|
-
"license": "
|
|
5
|
+
"license": "Apache-2.0",
|
|
6
6
|
"author": "quolu",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|