@nahisaho/katashiro 2.1.0 → 2.1.2
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/AGENTS.md +87 -3
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -81,6 +81,88 @@ import {
|
|
|
81
81
|
} from '@nahisaho/katashiro';
|
|
82
82
|
```
|
|
83
83
|
|
|
84
|
+
### ⚠️ 重要: 戻り値の型について
|
|
85
|
+
|
|
86
|
+
KATASHIROのAPIには**2種類の戻り値パターン**があります。コード生成時は必ず区別してください。
|
|
87
|
+
|
|
88
|
+
#### 1. 直接値を返すAPI（`isOk()` 不要）
|
|
89
|
+
|
|
90
|
+
以下のAPIは**直接値を返す**ため、`isOk()` を使用しません：
|
|
91
|
+
|
|
92
|
+
| API | 戻り値の型 | 使用例 |
|
|
93
|
+
|-----|-----------|-------|
|
|
94
|
+
| `WebSearchClient.search()` | `Promise<SearchResult[]>` | `const results = await client.search(query);` |
|
|
95
|
+
| `TextAnalyzer.analyze()` | `Promise<{ keywords, complexity, sentiment, ... }>` | `const analysis = await analyzer.analyze(text);` |
|
|
96
|
+
| `EntityExtractor.extract()` | `Promise<ExtractedEntities>` | `const entities = await extractor.extract(text);` |
|
|
97
|
+
| `SummaryGenerator.generate()` | `Promise<string>` | `const summary = await summarizer.generate(text);` |
|
|
98
|
+
| `ReportGenerator.generate()` | `Promise<string>` | `const report = await reportGen.generate(config);` |
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
// ✅ 正しい使い方
|
|
102
|
+
const results = await searchClient.search('AI');
|
|
103
|
+
console.log(`${results.length}件の結果`);
|
|
104
|
+
|
|
105
|
+
const analysis = await analyzer.analyze(text);
|
|
106
|
+
console.log(`キーワード: ${analysis.keywords.join(', ')}`);
|
|
107
|
+
|
|
108
|
+
const entities = await extractor.extract(text);
|
|
109
|
+
console.log(`${entities.all.length}個のエンティティ`);
|
|
110
|
+
|
|
111
|
+
const summary = await summarizer.generate(text);
|
|
112
|
+
console.log(`${summary.length}文字の要約`);
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
#### 2. `Result<T, E>` を返すAPI（`isOk()` 必須）
|
|
116
|
+
|
|
117
|
+
以下のAPIは**Result型を返す**ため、`isOk()` でチェックが必要です：
|
|
118
|
+
|
|
119
|
+
| API | 戻り値の型 | 使用例 |
|
|
120
|
+
|-----|-----------|-------|
|
|
121
|
+
| `WebScraper.scrape()` | `Promise<Result<ScrapingResult, Error>>` | `if (isOk(page)) { page.value.content }` |
|
|
122
|
+
| `WebScraper.scrapeMultiple()` | `Promise<Result<ScrapingResult, Error>[]>` | 各要素を`isOk()`でチェック |
|
|
123
|
+
| `SummaryGenerator.summarize()` | `Promise<Result<string, Error>>` | `if (isOk(result)) { result.value }` |
|
|
124
|
+
| `SummaryGenerator.generateSummary()` | `Promise<Result<string, Error>>` | `if (isOk(result)) { result.value }` |
|
|
125
|
+
| `TextAnalyzer.summarize()` | `Promise<Result<Summary, Error>>` | `if (isOk(summary)) { summary.value }` |
|
|
126
|
+
| `FactChecker.checkWithSources()` | `Promise<Result<FactCheckResultDetail, Error>>` | `if (isOk(result)) { ... }` |
|
|
127
|
+
| `FactChecker.detectConflicts()` | `Promise<Result<ConflictDetectionResult, Error>>` | `if (isOk(result)) { ... }` |
|
|
128
|
+
| `DocumentParser.parse()` | `Promise<Result<ParsedDocument, Error>>` | `if (isOk(doc)) { doc.value }` |
|
|
129
|
+
| `PDFParser.parse()` | `Promise<Result<ParsedDocument, Error>>` | `if (isOk(doc)) { ... }` |
|
|
130
|
+
| `DOCXParser.parse()` | `Promise<Result<ParsedDocument, Error>>` | `if (isOk(doc)) { ... }` |
|
|
131
|
+
| `XLSXParser.parse()` | `Promise<Result<ParsedDocument, Error>>` | `if (isOk(doc)) { ... }` |
|
|
132
|
+
| `ApiClient.getSafe()` | `Promise<Result<T, Error>>` | `if (isOk(response)) { ... }` |
|
|
133
|
+
| `ApiClient.postSafe()` | `Promise<Result<T, Error>>` | `if (isOk(response)) { ... }` |
|
|
134
|
+
| `CodeInterpreter.execute()` | `Promise<Result<ExecutionResult, Error>>` | `if (isOk(result)) { ... }` |
|
|
135
|
+
| `TrendAnalyzer.analyze()` | `Promise<Result<TrendAnalysisResult, Error>>` | `if (isOk(result)) { ... }` |
|
|
136
|
+
| `DiagramGenerator.generate*()` | `Promise<Result<DiagramOutput, Error>>` | `if (isOk(diagram)) { ... }` |
|
|
137
|
+
|
|
138
|
+
```typescript
|
|
139
|
+
// ✅ 正しい使い方（Result型のみ isOk() を使用）
|
|
140
|
+
const page = await scraper.scrape(url);
|
|
141
|
+
if (isOk(page)) {
|
|
142
|
+
console.log(page.value.content); // .value でアンラップ
|
|
143
|
+
} else {
|
|
144
|
+
console.error(page.error); // .error でエラー取得
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
// SummaryGenerator.summarize() もResult型
|
|
148
|
+
const summaryResult = await summarizer.summarize(text);
|
|
149
|
+
if (isOk(summaryResult)) {
|
|
150
|
+
console.log(summaryResult.value); // string
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
// ❌ 間違い（直接値を返すAPIに isOk() を使用）
|
|
154
|
+
const results = await searchClient.search('AI');
|
|
155
|
+
// if (isOk(results)) { ... } // エラー！results は配列
|
|
156
|
+
|
|
157
|
+
// ❌ 間違い（generate() と summarize() を混同）
|
|
158
|
+
const summary = await summarizer.generate(text); // これは直接string
|
|
159
|
+
// if (isOk(summary)) { ... } // エラー！summaryはstring
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
> **注意**: `SummaryGenerator` には2つのメソッドがあります：
|
|
163
|
+
> - `generate()` → 直接 `string` を返す（`isOk()` 不要）
|
|
164
|
+
> - `summarize()` → `Result<string, Error>` を返す（`isOk()` 必須）
|
|
165
|
+
|
|
84
166
|
---
|
|
85
167
|
|
|
86
168
|
## 📝 課題タイプ別の実装パターン
|
|
@@ -109,10 +191,12 @@ async function solveResearchProblem(topic: string) {
|
|
|
109
191
|
|
|
110
192
|
// 4. エンティティ抽出
|
|
111
193
|
const extractor = new EntityExtractor();
|
|
112
|
-
const allEntities = [];
|
|
194
|
+
const allEntities: Entity[] = [];
|
|
113
195
|
for (const content of contents) {
|
|
114
|
-
const
|
|
115
|
-
|
|
196
|
+
const extracted = await extractor.extract(content);
|
|
197
|
+
// extract() は ExtractedEntities オブジェクトを返す
|
|
198
|
+
// extracted.persons, extracted.organizations, extracted.urls など
|
|
199
|
+
allEntities.push(...extracted.all); // all プロパティで全エンティティ配列にアクセス
|
|
116
200
|
}
|
|
117
201
|
|
|
118
202
|
// 5. 要約生成
|